Skip to content

About

Markdown snapshot of a repository (with optional ZIP)

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

5 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 

Repository files navigation

SourcecodeSnapshot

Python License

Lightweight utility to produce a code-only Markdown snapshot of a repository.

This repository contains a single script: sourcecode_snapshot.py, which generates a Markdown file containing a small directory tree excerpt and concatenated source files (code-only). Optionally the script can also produce a ZIP archive including the generated Markdown and the selected source files.

Key points:

  • Script: sourcecode_snapshot.py
  • Default output: your_sourcecode_snapshot.md
  • ZIP option: --zip / -z
  • Configurable source and output paths: --src, --dst
  • Safe self-exclusion: sourcecode_snapshot.py never ends up in the snapshot

Features

  • Includes only selected file extensions and explicit filenames.
  • Skips common large/irrelevant directories (virtualenvs, models, outputs, recordings).
  • Skips very large files (configurable via --max-size).
  • Produces a short directory tree excerpt (configurable via --depth).
  • Attempts UTF-8 reading, falls back to latin-1.
  • Non-destructive: reads files and writes outputs only.
  • CLI options: source path, destination path, output filename, ZIP output, dry-run, verbosity, additional extensions/names, additional excluded folders.
  • Safe self-exclusion: the running sourcecode_snapshot.py file is never included — not from --src nor via --dst.

Included file types (default)

Extensions:

  • .py, .html, .yml, .yaml, .sh, .ps1, .txt, .service

Explicit filenames:

  • .env.example, .gitignore, .dockerignore, Dockerfile, Makefile

Default excluded directories:

  • .venv, venv, __pycache__, .git, .pytest_cache, .mypy_cache, models, outputs, recordings, node_modules, dist, build

Installation

No installation required. Copy sourcecode_snapshot.py to your project root or clone this repository:

git clone https://github.com/Betakontext/SourcecodeSnapshot.git
cd SourcecodeSnapshot


# (Optional) Make executable:

    BASH


        chmod +x sourcecode_snapshot.py

# Usage:
    
Place sourcecode_snapshot.py in the project root (or install it to your PATH) and run:

    BASH

        python3 sourcecode_snapshot.py

        #f.e. to get contents of a specific folder from root, if sourcecode_snapshot.py in root:
        
        python3 sourcecode_snapshot.py --src yourfolder --dst ./ --out ./yourfoldercontents_aktuell.md

# Common options:

    --src: Source directory to scan (default: .).
    --dst: Destination directory for generated files (default: .).
    --out, -o: Markdown output filename (default: your_sourcecode_snapshot.md).
    --zip, -z: Optional ZIP output filename/path relative to --dst; creates a ZIP containing the Markdown and source files.
    --max-size: Maximum file size (bytes) to include (default: 30 MiB).
    --depth: Directory tree excerpt depth (default: 2).
    --dry-run: Show what would be included; do not write files.
    --verbose, -v: Verbose output.
    --allow-ext: Add an allowed extension (e.g., --allow-ext .md), can be used multiple times.
    --allow-name: Add an allowed filename (e.g., --allow-name README.md), can be used multiple times.
    --exclude-dir: Additional directory basename to exclude; can be used multiple times.


# dry-run to check without writing

BASH

    python3 sourcecode_snapshot.py --dry-run --verbose

# Output

your_sourcecode_snapshot.md (or your chosen --out) — a Markdown file that begins with
a small directory tree excerpt and continues with the contents of each included source file,
each within a fenced code block.

If --zip is provided, a ZIP archive is created that contains the Markdown file and the included source files preserving relative paths.

CI integration (optional)

You can run the script in CI to produce artifacts or commit snapshots to a branch. Example GitHub Actions badge (replace with actual workflow if you add it):

CI badge placeholder (add a workflow and replace workflow-name):


https://github.com/<your-org>/<your-repo>/actions/workflows/<workflow-file>.yaml/badge.svg



## Contributing

Contributions welcome.
Suggestions:

Add more CLI options (output formats: tar.gz, commit to branch). Add filtering by .gitignore or by git tracked files only.
Add unit tests (pytest) for gather and tree functionality.
Windows path handling improvements and encoding tests.

Fork and please open issues or PRs.

This project is licensed under the MIT License — see the accompanying LICENSE file for details.

If this helped, star the repo ⭐


About

Markdown snapshot of a repository (with optional ZIP)

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages