dirpluck

dirpluck is a CLI tool for recording a recurring decision, "which files belong together?", in TOML and building a ZIP archive from the same declared intent later.

Rather than copying everything around a workspace like a backup, it is intended to package only the material needed for an explicit purpose such as review, handoff, research, recurring work, or a working context shared with an LLM.

Where it fits

Gather fixed material from several locations

When files for one purpose live in different directories, they can be fixed in a Configuration as Companions. A Companion source directory does not need to live near the Configuration and may directly reference another filesystem location.

For example, a review package can combine proposal material, research results, and legal references, or a recurring workflow can gather the same kinds of material each time. A Configuration may consist entirely of Companions when nothing needs to vary at runtime.

Attach stable references to a changing subject

Use a Target when the same selection rules should be applied to different projects, submissions, cases, or similar subjects. The Target selection stays in the Configuration while the concrete source directory is selected when dirpluck runs.

By default, Targets are direct child directories of the current working directory. When the Configuration workspace and the Target material should live in different places, define a named Target location and select a direct child through a logical reference such as work/project. work/ selects every eligible direct child directory of that location as a Target. Targets are deliberately one level deep: directories inside a Target are not themselves Target candidates.

Stable guidelines, templates, and reference material can remain as Companions in the same archive. This lets the Configuration workspace, runtime Targets, and fixed reference material live independently.

Reuse an extraction intent declared elsewhere

When a related project already has a Configuration, a Configuration import can use it as an inner layer instead of copying the same definitions into the parent Configuration.

Exact import ordering, shadowing, and filesystem-boundary rules live in docs/SPECIFICATION.md. For the authoring forms needed to write a Configuration, see docs/CONFIGURATION.md.

Why keep the intent as a declaration

For a one-off archive, creating a ZIP by hand may be simpler. dirpluck is useful when the same kind of judgment needs to be made again.

A Configuration records what is required, what is optional, what should be excluded, and which fixed references belong with the package. That intent does not have to be reconstructed from shell history, conversation history, or memory. --dry-run can show how the current filesystem resolves before anything is written.

For LLM-assisted work, dirpluck prepares the material on the local filesystem as an Archive. That Archive can be uploaded to a non-local conversational LLM or placed into the workspace used by a local agent. This workflow does not assume that the LLM operates dirpluck itself.

Configuration and filesystem trust

When creating an Archive that will leave the local environment, review the selection before creating it. dirpluck does not infer which files are sensitive; explicitly exclude material that should not be collected. For example:

exclude = [".git/", ".env*", "*.pem", "*.key"]

This is only an example; project-specific sensitive material may use different names or locations. See docs/TRUST.md for how to treat Configurations, absolute paths, overwrite behavior, and Archives that will leave the local environment.

A small example

The following Configuration combines a runtime Target with fixed review guidelines:

[target]
description = "The project currently under review."
include_if_exists = ["README.md", "src", "tests"]
exclude = [".git/", "__pycache__/", "*.pyc"]
skip = ["archive", "tmp-*"]
if_empty = "allow"

[target.location.work]
path = "/srv/projects"
skip = ["archive"]

[companion.guidelines]
path = "review-guidelines"
description = "Guidelines used for every review."
include = ["*.md"]

[output]
path = "artifacts/review.zip"
if_exists = "overwrite"

dirpluck work/example --dry-run
dirpluck work/example

For all Configuration fields and a larger example, see docs/CONFIGURATION.md. For CLI options and Configuration discovery, see docs/CLI.md.

Installation

Python 3.11 or later is required. The current release is 0.8.0.

pip install dirpluck
dirpluck --version

dirpluck has no third-party runtime dependencies.

Documentation

The documents are separated by reading purpose:

• GLOSSARY.md: the concepts used throughout the documentation.
• docs/CONFIGURATION.md: how to write TOML Configurations.
• docs/CLI.md: how to operate the CLI.
• docs/SPECIFICATION.md: exact rules for resolution, matching, filesystem boundaries, archives, output, and validation.
• docs/TRUST.md: the trust boundary for Configurations and filesystem operations.
• CHANGELOG.md: release history.

The wheel includes compact dirpluck/docs/CONFIGURATION.md and dirpluck/docs/CLI.md references together with dirpluck/docs/TRUST.md, so the trust model remains available in an installed package. For more detail, use the documentation in the source distribution or repository.

Public interface

The compatibility-supported public surface is the dirpluck CLI and the TOML Configuration format. Python modules inside the package are internal implementation unless explicitly documented as a public API.