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.pynever ends up in the snapshot
- 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.pyfile is never included — not from--srcnor via--dst.
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
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 ⭐