Crate dirgrab_lib

dirgrab 📁⚡

dirgrab is a simple command-line tool to grab the content of files within a directory and concatenate them, suitable for feeding project contexts into language models.

It intelligently uses Git context when available (git ls-files) to only include tracked files (respecting .gitignore), but also works seamlessly on plain directories.

Features:

• Concatenates file contents to stdout, a file (-o), or the clipboard (-c).
• Uses git ls-files in Git repositories (respects .gitignore by default).
• Optionally includes untracked files in Git repos (-u).
• Works on non-Git directories by walking the file tree.
• Allows custom exclude patterns (-e) using .gitignore glob syntax.
• Includes file headers (--- FILE: path/to/file ---) by default (disable with --no-headers).
• Skips binary/non-UTF8 files with a warning.

Installation

Ensure you have Rust and Cargo installed. Then, install dirgrab using Cargo:

cargo install dirgrab

Verify the installation:

dirgrab --version

Usage

dirgrab [OPTIONS] [TARGET_PATH]

Arguments:

• [TARGET_PATH]: Optional path to the directory or Git repository to process. Defaults to the current working directory.

Options:

• -o, --output <FILE>: Write output to a file instead of stdout.
• -c, --clipboard: Copy output to the system clipboard.
• --no-headers: Disable the default ‘— FILE: … —’ headers.
• -e, --exclude <PATTERN>: Add glob patterns to exclude files/dirs (can be used multiple times).
• -u, --include-untracked: [Git Mode Only] Include untracked files (still respects .gitignore and excludes).
• -v, -vv, -vvv: Increase verbosity level for logging.
• -h, --help: Print help information.
• -V, --version: Print version information.

Examples:

1. Grab tracked files from current Git repo to stdout (default headers):

   dirgrab

2. Grab files from current directory, disable headers, output to file:

   dirgrab --no-headers -o output.txt

3. Grab tracked files from specific repo path, copy to clipboard:

   dirgrab -c ../my-other-project/

4. Grab tracked + untracked files, excluding logs and build dirs:

   dirgrab -u -e "*.log" -e "target/" -e "build/"

5. Grab all files from a non-Git directory, excluding temp files:\

   dirgrab -e "*.tmp" /path/to/non-git-dir

Behavior Details

• Git Mode: If the target directory is detected as part of a Git repository, dirgrab uses git ls-files to determine which files to include. This automatically respects .gitignore rules. The -u flag adds untracked files, still respecting .gitignore. Exclusions (-e) are passed to git ls-files.
• Non-Git Mode: If the target directory is not a Git repository, dirgrab walks the directory tree. It includes all files found unless they match an exclusion pattern (-e). .gitignore files are ignored in this mode.
• File Encoding: dirgrab attempts to read files as UTF-8. If a file cannot be decoded (likely binary), it is skipped, and a warning is printed to stderr (visible with -v).
• Output: By default, file content is concatenated directly. With headers enabled (default), each file’s content is preceded by --- FILE: <relative_path> ---. An extra newline is added between files for readability.

Library (dirgrab-lib)

The core logic is available as a separate library crate (dirgrab-lib) for use in other Rust projects. See its documentation on docs.rs (link will work after publishing).

License

This project is licensed under either of:

• Apache License, Version 2.0, (LICENSE-APACHE or link)
• MIT license (LICENSE-MIT or link)

at your option.

Contribution

Contributions are welcome! Please feel free to submit issues and pull requests.

Structs

GrabConfig

Configuration for the dirgrab operation.

Enums

GrabError

Errors that can occur during the dirgrab library operations.

Functions

grab_contents

Performs the main dirgrab operation based on the provided configuration.

Type Aliases

GrabResult

A convenience type alias for Result<T, GrabError>.