Contextify

Contextify is a Rust utility that captures the structure and contents of a project directory and saves them into a text file. It's designed for quick documentation of your project's file system.

Features

• Complete Capture: Records the entire file structure and contents of the project.
• Customizable Filters: Offers blacklist and whitelist options for targeted scanning.
• Command-Line Interface: Simple and easy-to-use command-line tool.
• Parallel Processing: Optimized for speed using Rust's parallelism capabilities.
• Gitignore-Style Patterns: Uses the same pattern syntax as .gitignore for intuitive filtering.

Installation

From Crates

cargo install contextify

From Source

Clone the repository and build the project:

git clone https://github.com/suenot/contextify.git
cd contextify
cargo install --path .

Usage

Navigate to your project directory and run:

contextify

By default, Contextify will scan all files and directories in the current folder and produce an output file called project_contents.txt.

Initialize Global Configuration Files

To create global configuration files in your home directory:

contextify init

This will create ~/.contextify-blacklist and ~/.contextify-whitelist files.

Locate the Configuration Files

To see where Contextify's configuration files are located:

contextify show-locations

This will print the paths to both local and global configuration files.

Filtering Options

Using Configuration Files

• --blacklist: Use the blacklist defined in the .blacklist file (or ~/.contextify-blacklist).
• --whitelist: Use the whitelist defined in the .whitelist file (or ~/.contextify-whitelist).
• --gitignore: Use the patterns from the project's .gitignore file as part of blacklist.

Using Custom Configuration Files

• --blacklist-file <PATH>: Use a custom blacklist file.
• --whitelist-file <PATH>: Use a custom whitelist file.

Direct Pattern Specification

• --blacklist-patterns <PATTERNS>: Specify blacklist patterns directly (comma-separated).
• --whitelist-patterns <PATTERNS>: Specify whitelist patterns directly (comma-separated).

Output and Information

• -o, --output <FILE>: Specify the output file (default: project_contents.txt).
• -s, --stats: Display performance statistics and token estimates.
• -h, --help: Show brief help information.
• -V, --version: Show version information.

Commands

• contextify full-help: Show detailed help information.
• contextify version: Show detailed version information.
• contextify init: Initialize global configuration files.
• contextify show-locations: Show paths to configuration files.

Examples

Use the default blacklist:

contextify --blacklist

Use the project's .gitignore file:

contextify --gitignore

Combine .gitignore with custom patterns:

contextify --gitignore --blacklist-patterns "*.tmp,*.bak"

Use the default whitelist:

contextify --whitelist

Use custom patterns:

contextify --blacklist-patterns "target/,.git/,*.log" --output my_project.txt

Use both blacklist and whitelist:

contextify --blacklist --whitelist

Use with statistics:

contextify --stats

Show detailed help:

contextify full-help

Configuration Files

Contextify respects two types of configuration files:

1. Blacklist (.blacklist): Exclude certain files/directories.
2. Whitelist (.whitelist): Include only certain files/directories.

The configuration files can be found in:

• Local: ./config/.blacklist and ./config/.whitelist in the project
• Global: ~/.contextify-blacklist and ~/.contextify-whitelist in the home directory

Example .blacklist File

.DS_Store
target/
*.log

Example .whitelist File

*.rs
*.md
*.toml

Algorithm

The following diagram illustrates the core algorithm of Contextify:

flowchart TD
    A[Start] --> B[Parse Command Line Arguments]
    B --> C{Command Specified?}
    C -->|Yes| D[Execute Command]
    C -->|No| E[Start Processing Project]
    
    E --> F[Read Configuration Files]
    F --> G[Process .gitignore if --gitignore]
    
    G --> H[Build File Filters]
    H --> I[Apply Blacklist Patterns]
    H --> J[Apply Whitelist Patterns]
    
    I --> K[Traverse Directory Structure]
    J --> K
    
    K --> L[Filter Files]
    L --> M[Process Files in Parallel]
    M --> N[Read File Contents]
    
    N --> O[Sort Results]
    O --> P[Generate Project Structure]
    P --> Q[Generate File Contents]
    
    Q --> R[Save to Output File]
    R --> S[Display Statistics if --stats]
    S --> T[End]
    D --> T

Processing Steps:

1. Parse Command Line Arguments: Process all options and determine operation mode.
2. Configuration Loading: Load blacklist/whitelist patterns from files or command line arguments.
3. File Selection:
   • Apply blacklist to exclude unwanted files
   • Apply whitelist to include only specific files
   • Respect .gitignore patterns if requested
4. Parallel Processing: Use Rust's parallel processing to efficiently read and process files.
5. Output Generation:
   • Generate a hierarchical view of the project structure
   • Include file contents with proper formatting
6. Statistics Calculation:
   • Count files, lines, and characters
   • Estimate token usage for AI context purposes
   • Measure performance metrics

Performance

Contextify is optimized for speed using Rust's concurrency features, making it significantly faster than the Python implementation (snap2txt).

License

Contextify is open-sourced software licensed under the MIT license.

Author

Eugen Soloviov (suenot)