reposcope 0.3.4

Collect repository files into a single document for easy sharing with AI assistants

RepoScope

RepoScope

RepoScope is a command-line tool designed to simplify the process of sharing repository contents, especially when working with AI assistants or code review platforms. It helps to quickly and easily share the entire context of a code project without manually copying and pasting individual files. It also allows user to define the content of which files they want to see in the generated output file with flexible pattern matching.

Quickstart

Install with pip:

pip install reposcope

Basic Usage

Create a snapshot of your repository:

# In your project directory, run:
reposcope

# This creates context.txt with all your files

Choose which files to include:

# Only share Python source files
reposcope -i "*.py"

# Only share files from src directory and documentation
reposcope -i "src/*" "*.md"

Skip unwanted files:

# Skip log files and build directory
reposcope -x "*.log" "build/"

# Use your existing .gitignore file
reposcope -g   # This skips the same files that git ignores

Save your preferred patterns for reuse:

# Create a profile for source code reviews
reposcope profile create source --mode include
reposcope profile add source "src/*.py" "tests/*.py" "*.md"

# Use it later
reposcope -p source

Output Format

RepoScope generates a context.txt file that looks like this:

Repository: my-project

File Tree:
└── src/main.py
└── src/utils.py
└── README.md

File Contents:

--- src/main.py ---
def main():
    print("Hello World!")
...

Command Line Options

Short	Long	Description
-g	--use-gitignore	Use .gitignore from current dir
-x	--exclude	Exclude patterns
-X	--exclude-file	File with exclude patterns
-i	--include	Include patterns
-I	--include-file	File with include patterns
-o	--output	Output file (default: context.txt)
-d	--dir	Repository directory
-v	--verbose	Show debug logs
-p	--profile	Use a saved profile

Key Concepts

Basic File Selection

Two ways to select files:

1. Exclude Mode (-x): Start with all files, remove unwanted ones

   reposcope -x "build/" "*.log"  # Everything except builds and logs
   

2. Include Mode (-i): Start with no files, add wanted ones

   reposcope -i "src/*.py" "*.md"  # Only Python files and docs
   

Pattern Matching

RepoScope uses .gitignore-style pattern matching:

• * matches any characters except /: *.py, src/*.js
• ? matches one character: test?.py matches test1.py
• ** matches directories: src/**/*.py matches all Python files under src
• / at start matches from root: /test.py only matches in root
• / at end matches directories: build/ matches directory and contents
• ! negates pattern: !test_*.py excludes test files.

⚠ WARNING! In Linux (and other Unix-like shells like Bash, Zsh), the ! character has special meaning - it's used for history expansion. This means:

• Direct use of ! often fails: Using !pattern directly will typically be interpreted by the shell before it gets to your program. Quoting is required: You generally need to quote the ! character to prevent shell interpretation:
• Single quotes: '!pattern' (most reliable)
• Escaped: !pattern (works in some shells)
• Double quotes with escaping: "!pattern" (needed in some contexts)

Pattern Symmetry

Include and exclude modes are imcompatible (you have to pick one for one use!) but complementary:

# These do opposite things:
reposcope -i "*.py"           # Only Python files
reposcope -x '!*.py'          # Everything except Python files

# These are equivalent:
reposcope -x "*" '!*.py'      # Exclude all but Python
reposcope -i "*.py"           # Include only Python

Profiles

Profiles help you save and reuse pattern collections. Instead of typing the same patterns repeatedly, you can save them in a profile and reuse them with a single command.

Profile Commands

Command	Arguments	Description
create	name --mode [include|exclude]	Create new profile
delete	name	Delete existing profile
add	name pattern [pattern...]	Add patterns to profile
remove	name pattern [pattern...]	Remove patterns from profile
import	name file	Import patterns from file
export	name	Export patterns to stdout
list_profiles	-	List all available profiles
show	name	Show profile details

Basic Profile Usage

Create and use a profile:

# Create profile for Python development
reposcope profile create python --mode include
reposcope profile add python "*.py" "requirements.txt"

# Use the profile
reposcope -p python

List and inspect profiles:

# See all profiles
reposcope profile list_profiles

# Show specific profile
reposcope profile show python

Organizing Patterns with Profiles

You can create different profiles for different tasks:

# Profile for code review
reposcope profile create review --mode include
reposcope profile add review "src/" "tests/" "*.md"

# Profile for documentation work
reposcope profile create docs --mode include
reposcope profile add docs "**/*.md" "docs/" "examples/"

# Profile for excluding build artifacts
reposcope profile create clean --mode exclude
reposcope profile add clean "build/" "dist/" "*.pyc" "__pycache__/"

Using Pattern Files

You can import patterns from files:

# patterns.txt:
# Source files
*.py
src/
tests/
# Documentation
*.md
docs/

# Import patterns
reposcope profile create dev --mode include
reposcope profile import dev patterns.txt

Export and Share Profiles

Share your profiles with team members:

# Export patterns to a file
reposcope profile export myprofile > myprofile_patterns.txt

# Send file to colleague, they can import it:
reposcope profile create myprofile --mode include
reposcope profile import myprofile myprofile_patterns.txt

Pro Tips for Profiles

1. Combine include and exclude profiles:

   # Profile for source code
   reposcope profile create source --mode include
   reposcope profile add source "src/**/*.py"
   
   # Profile for artifacts to ignore
   reposcope profile create artifacts --mode exclude
   reposcope profile add artifacts "*.pyc" "__pycache__"
   
   # Use them together (include source, then exclude artifacts)
   reposcope -p source -x "*.pyc" "__pycache__"
   

2. Use project-specific profiles:

   # Django project profile
   reposcope profile create django --mode include
   reposcope profile add django "*.py" "templates/" "static/"
   
   # Flask project profile
   reposcope profile create flask --mode include
   reposcope profile add flask "*.py" "templates/" "static/" "instance/"
   

3. Create focused profiles:

   # Tests only
   reposcope profile create tests --mode include
   reposcope profile add tests "tests/**/*.py" "pytest.ini" "conftest.py"
   
   # Database related files
   reposcope profile create db --mode include
   reposcope profile add db "models.py" "migrations/" "schema.sql"
   

Profile Storage

Profiles are stored in ~/.config/reposcope/profiles.json. Each profile maintains:

• Name
• Mode (include/exclude)
• List of patterns

Examples with Explanations

1. Development profile:

   reposcope profile create dev --mode include
   # Add source files
   reposcope profile add dev "src/**/*.py"
   # Add test files but exclude integration tests
   reposcope profile add dev "tests/" '!tests/integration/'
   # Add documentation
   reposcope profile add dev "*.md" "docs/"
   

2. Cleanup profile:

   reposcope profile create cleanup --mode exclude
   # Exclude common build artifacts
   reposcope profile add cleanup "build/" "dist/" "*.egg-info"
   # Exclude Python cache files
   reposcope profile add cleanup "**/__pycache__" "*.pyc" "*.pyo"
   # Exclude common editor/IDE files
   reposcope profile add cleanup ".vscode/" ".idea/" "*.swp"
   

3. Documentation profile:

   reposcope profile create docs --mode include
   # Include all documentation files
   reposcope profile add docs "**/*.md" "**/*.rst"
   # Include examples and tutorials
   reposcope profile add docs "docs/" "examples/" "tutorials/"
   # Exclude work in progress
   reposcope profile add docs '!**/draft/' '!**/*_wip.*'
   

More Examples

AI Code Review

# Share source and tests, exclude temporary files
reposcope -i "src/**/*.py" "tests/**/*.py" '!**/tmp/*'

# Everything except build artifacts and caches
reposcope -g -x "*.pyc" "**/__pycache__/"

Documentation Work

# Only documentation files
reposcope -i "**/*.md" "docs/" "examples/"

# Share docs but exclude drafts
reposcope -i "docs/" '!docs/drafts/'

Pro Tips

1. Combine .gitignore with extra exclusions:

   reposcope -g -x "*.tmp" "scratch/"
   

2. Override .gitignore exclusions:

   reposcope -g -x '!build/important.txt'
   

3. Use directory patterns effectively:

   # All files in src except tests
   reposcope -i "src/" '!src/tests/'
   

4. Chain patterns for complex selections:

   # Python files except tests, plus documentation
   reposcope -i "*.py" '!test_*.py' "docs/*.md"
   

Development

1. Install development dependencies:

   pip install -e ".[dev]"
   

2. Run tests:

   pytest
   

Limitations

• Currently Linux-only
• Requires Python 3.9+
• Large repositories might generate very big context files. Proceed carefully. (However, it does skip binary files)

License

MIT License