Metadata-Version: 2.4
Name: pre-commit-snippets
Version: 2.0.1.dev20260421173409
Summary: Pre-commit hook that syncs markdown snippets from a central repository
License-Expression: MIT
Project-URL: Homepage, https://github.com/RemoteRabbit/pre-commit-snippets
Project-URL: Documentation, https://remoterabbit.github.io/pre-commit-snippets
Project-URL: Repository, https://github.com/RemoteRabbit/pre-commit-snippets
Project-URL: Issues, https://github.com/RemoteRabbit/pre-commit-snippets/issues
Keywords: pre-commit,snippets,markdown,documentation,sync
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Pre-processors
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: docs
Requires-Dist: mkdocs-material[imaging]>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
Requires-Dist: mkdocs-git-revision-date-localized-plugin>=1.2; extra == "docs"
Requires-Dist: mkdocs-git-committers-plugin-2>=2.2; extra == "docs"
Requires-Dist: mkdocs-minify-plugin>=0.8; extra == "docs"
Requires-Dist: mkdocs-macros-plugin>=1.0; extra == "docs"
Requires-Dist: mkdocs-redirects>=1.2; extra == "docs"
Requires-Dist: mike>=2.0; extra == "docs"
Requires-Dist: pillow>=10.0; extra == "docs"
Requires-Dist: cairosvg>=2.7; extra == "docs"

# pre-commit-snippets

[![PyPI](https://img.shields.io/pypi/v/pre-commit-snippets)](https://pypi.org/project/pre-commit-snippets/)
[![CI](https://github.com/RemoteRabbit/pre-commit-snippets/actions/workflows/ci.yaml/badge.svg)](https://github.com/RemoteRabbit/pre-commit-snippets/actions/workflows/ci.yaml)
[![Documentation](https://img.shields.io/badge/docs-latest-blue)](https://remoterabbit.github.io/pre-commit-snippets/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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`:

```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:

```yaml
# 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:

```markdown
# 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

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

| Option | Description |
|--------|-------------|
| `--dry-run` | Preview changes without modifying files |
| `--verbose`, `-v` | Print info-level logs (files being processed, updates) |
| `--debug` | Print debug-level logs with timestamps (commands, hashes, paths) |
| `--config PATH` | Path to config file (default: `.pre-commit-snippets-config.yaml` in repo root) |

### Examples

```bash
# 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](CONTRIBUTING.md) for development setup, conventional commits, and release process.

## License

MIT
