RepoSnap

Overview

reposnap is a Python tool designed to generate a Markdown file that documents the structure and contents of a Git project. It provides both a command-line interface (CLI) and a graphical user interface (GUI) for ease of use. This tool is particularly useful for creating a quick overview of a project's file hierarchy, including optional syntax-highlighted code snippets.

Features

• Command-Line Interface (CLI): Quickly generate documentation from the terminal.
• Graphical User Interface (GUI): A user-friendly GUI if you want to select files and directories interactively.
• Syntax Highlighting: Includes syntax highlighting for known file types in the generated Markdown file.
• Structure Only Option: The --structure-only flag can be used to generate the Markdown file with just the directory structure, omitting the contents of the files.
• Gitignore Support: Automatically respects .gitignore patterns to exclude files and directories.
• Include and Exclude Patterns: Use --include and --exclude to specify patterns for files and directories to include or exclude.
• Changes Only Mode: Use -c or --changes to snapshot only uncommitted files (staged, unstaged, untracked, and stashed changes).

Installation

You can install reposnap using pip:

pip install reposnap

Alternatively, you can clone the repository and install the required dependencies:

git clone https://github.com/username/reposnap.git
cd reposnap
pip install -r requirements.lock

Usage

Command-Line Interface

To use reposnap from the command line, run it with the following options:

reposnap [-h] [-o OUTPUT] [--structure-only] [--debug] [-i INCLUDE [INCLUDE ...]] [-e EXCLUDE [EXCLUDE ...]] [-c] paths [paths ...]

• paths: One or more paths (files or directories) within the repository whose content and structure should be rendered.
• -h, --help: Show help message and exit.
• -o, --output: The name of the output Markdown file. Defaults to output.md.
• --structure-only: Generate a Markdown file that includes only the project structure, without file contents.
• --debug: Enable debug-level logging.
• -i, --include: File/folder patterns to include. For example, -i "*.py" includes only Python files.
• -e, --exclude: File/folder patterns to exclude. For example, -e "*.md" excludes all Markdown files.
• -c, --changes: Use only files that are added/modified/untracked/stashed but not yet committed.

Pattern Matching

• Pattern Interpretation: Patterns follow gitignore-style syntax but with a twist.

  • Patterns without Wildcards: If a pattern does not contain any wildcard characters (*, ?, or [), it is treated as *pattern*. This means it will match any file or directory containing pattern in its name.
  • Patterns with Wildcards: If a pattern contains wildcard characters, it retains its original behavior.

• Examples:

  • -e "gui": Excludes any files or directories containing "gui" in their names.
  • -i "*.py": Includes only files ending with .py.
  • -e "*.test.*": Excludes files with .test. in their names.

Only Snapshot Your Current Work

The -c or --changes flag allows you to generate documentation for only the files that have been modified but not yet committed. This includes:

• Staged changes: Files that have been added to the index with git add
• Unstaged changes: Files that have been modified but not yet staged
• Untracked files: New files that haven't been added to Git yet
• Stashed changes: Files that are stored in Git stash entries

This is particularly useful when you want to:

• Document only your current work-in-progress
• Create a snapshot of changes before committing
• Review what files you've been working on

Examples:

1. Generate documentation for only your uncommitted changes:

   reposnap . -c
   

2. Combine with structure-only for a quick overview:

   reposnap . -c --structure-only
   

3. Filter uncommitted changes by file type:

   reposnap . -c -i "*.py"
   

4. Exclude test files from uncommitted changes:

   reposnap . -c -e "*test*"
   

Examples

1. Generate a full project structure with file contents:

   reposnap .
   

2. Generate a project structure only:

   reposnap my_project/ --structure-only
   

3. Generate a Markdown file including only Python files:

   reposnap my_project/ -i "*.py"
   

4. Generate a Markdown file excluding certain files and directories:

   reposnap my_project_folder my_project_folder_2 -e "tests" -e "*.md"
   

5. Exclude files and directories containing a substring:

   reposnap my_project/ -e "gui"
   

6. Document only your current uncommitted work:

   reposnap . -c
   

Graphical User Interface

reposnap also provides a GUI for users who prefer an interactive interface.

To launch the GUI, simply run:

reposnap-gui

Using the GUI

1. Select Root Directory: When the GUI opens, you can specify the root directory of your Git project. By default, it uses the current directory.

2. Scan the Project: Click the "Scan" button to analyze the project. The GUI will display the file tree of your project.

3. Select Files and Directories: Use the checkboxes to select which files and directories you want to include in the Markdown documentation. Toggling a directory checkbox will toggle all its child files and directories.

4. Generate Markdown: After selecting the desired files, click the "Render" button. The Markdown file will be generated and saved as output.md in the current directory.

5. Exit: Click the "Exit" button to close the GUI.

Testing

To run the tests, use the following command:

pytest tests/

Ensure that you have the pytest library installed:

pip install pytest

License

This project is licensed under the MIT License.

Acknowledgments

• GitPython - Used for interacting with Git repositories.
• pathspec - Used for pattern matching file paths.
• Urwid - Used for creating the GUI interface.