pre-commit-snippets

A pre-commit hook that automatically syncs markdown snippets from a central repository into your documentation files.

Features

• Marker-based replacement: Uses <!-- SNIPPET-START: name --> / <!-- SNIPPET-END --> markers to identify replaceable blocks
• SHA-256 caching: Only rewrites blocks when the central snippet has actually changed, avoiding unnecessary file churn
• Automatic staging: Modified files are automatically staged for commit
• Branch/tag support: Pin snippets to a specific branch or tag
• Dry-run mode: Preview changes without modifying files
• Debug logging: Detailed logging for troubleshooting

Installation

Using pre-commit framework

Add this to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/RemoteRabbit/pre-commit-snippets
    rev: v1.0.4  # Use the latest tag
    hooks:
      - id: snippet-sync

Manual installation

1. Clone this repository
2. Create a .pre-commit-snippets-config.yaml configuration file (see below)
3. Run python main.py before committing

Configuration

Create a .pre-commit-snippets-config.yaml file in your repository root:

# URL of the repository containing your snippets (required)
snippet_repo: https://github.com/your-org/snippets.git

# Branch or tag to use (optional, default: default branch)
snippet_branch: main

# Subdirectory within the snippet repo where snippets are stored (optional)
snippet_subdir: snippets

# File extension for snippet files (optional, default: .md)
snippet_ext: .md

# Path for the snippet hash cache file (optional, default: .snippet-hashes.json)
cache_path: .snippet-hashes.json

# List of files to process (required)
target_files:
  - README.md
  - docs/CONTRIBUTING.md
  - docs/SECURITY.md

Usage

In your markdown files, wrap the areas you want to sync with snippet markers:

# My Project

<!-- SNIPPET-START: license-notice -->
This content will be replaced with the contents of `license-notice.md` from your snippet repo.
<!-- SNIPPET-END -->

## Other content...

When the hook runs, it will:

1. Clone the snippet repository (shallow clone)
2. Find all SNIPPET-START / SNIPPET-END marker pairs
3. Replace the content between markers with the corresponding snippet file
4. Cache hashes to avoid rewriting unchanged blocks
5. Stage any modified files

Command Line Options

pre-commit-snippets [OPTIONS]
# or
python main.py [OPTIONS]

Examples

# Normal run
pre-commit-snippets

# Preview what would change
pre-commit-snippets --dry-run

# See detailed processing info
pre-commit-snippets --verbose

# Debug issues with full detail
pre-commit-snippets --debug

Cache File

The hook creates a .snippet-hashes.json file to track which snippets have been applied. You should commit this file to avoid unnecessary rewrites on other machines.

Project Structure

pre-commit-snippets/
├── main.py                      # CLI entry point
├── pre_commit_snippet/
│   ├── __init__.py              # Package init
│   ├── cache.py                 # Hash computation and caching
│   ├── cli.py                   # Argument parsing and main logic
│   ├── config.py                # Configuration loading
│   ├── git.py                   # Git operations
│   ├── logging.py               # Logging configuration
│   └── snippet.py               # Snippet replacement logic
└── tests/
    └── test_main.py             # Test suite

Development

See CONTRIBUTING.md for development setup, conventional commits, and release process.

License

MIT