Skip to content

Quick Start

Get path-comment-hook up and running in 5 minutes. This guide will walk you through adding path headers to your first project.

Prerequisites

  • Python 3.8+ installed
  • A Git repository with source code files

Step 1: Install path-comment-hook

Choose your preferred installation method:

pip install path-comment-hook

pipx install path-comment-hook

poetry add --group dev path-comment-hook

Step 2: Test the Installation

Verify the installation worked:

path-comment-hook --version

You should see version information displayed.

Step 3: Try It Out

Let's add path headers to a sample file:

  1. Create a test file: 

    mkdir -p src/utils
cat > src/utils/helper.py << 'EOF'
def greet(name):
    return f"Hello, {name}!"

def add_numbers(a, b):
    return a + b
EOF

  2. Run path-comment-hook: 

    path-comment-hook src/utils/helper.py

  3. Check the result: 

    cat src/utils/helper.py

You should see: 

# src/utils/helper.py

def greet(name):
    return f"Hello, {name}!"

def add_numbers(a, b):
    return a + b

Success! The path header has been added to your file.

Step 4: Process Multiple Files

Process all Python files in your project:

# Process all files in src/ directory
path-comment-hook --all src/

# Or process your entire project
path-comment-hook --all

Dry Run First

Use --check mode to see what would be changed without modifying files: 

path-comment-hook --check --all

For automatic path header management, set up pre-commit:

  1. Install pre-commit (if not already installed): 

    pip install pre-commit

  2. Create .pre-commit-config.yaml in your project root: 

    repos:
  - repo: https://github.com/Shorzinator/path-comment-hook
    rev: v0.3.0  # Use the latest version
    hooks:
      - id: path-comment

  3. Install the hook: 

    pre-commit install

  4. Test it: 

    # Run on all files
pre-commit run path-comment --all-files

# Or make a commit to trigger automatically
git add .
git commit -m "Add path-comment-hook"

Common Use Cases

Add Headers to Existing Project

# Check what would be changed
path-comment-hook --check --all

# Apply changes
path-comment-hook --all

# Commit the changes
git add .
git commit -m "Add file path headers"

Remove Headers

# Remove all path headers
path-comment-hook --delete --all

# Or check what would be removed first
path-comment-hook --delete --check --all

Process Specific File Types

# Only Python files
find . -name "*.py" -exec path-comment-hook {} +

# Multiple file types
path-comment-hook src/**/*.py src/**/*.js

Understanding the Output

When you run path-comment-hook, you'll see output like:

Processing files...
✓ src/utils/helper.py - CHANGED
✓ src/main.py - OK (already has header)
⚠ binary_file.so - SKIPPED
  • CHANGED: Header was added or updated
  • OK: File already has the correct header
  • SKIPPED: File was skipped (binary, unsupported type, etc.)

Configuration (Optional)

Create a pyproject.toml configuration for custom behavior:

[tool.path-comment]
exclude_globs = [
    "*.md",
    "tests/fixtures/*",
    "docs/*"
]

See the Configuration Guide for all options.

Troubleshooting

Files Not Being Processed

  • Check if the file type is supported: Supported File Types
  • Verify the file isn't excluded by default patterns
  • Use --verbose for detailed output

Headers Look Wrong

Pre-commit Issues

  • Make sure you have the latest version in .pre-commit-config.yaml
  • Run pre-commit autoupdate to update hooks
  • Use pre-commit run --all-files to test

What's Next?

Now that you have the basics working:

Example Project

Here's what a typical project looks like after running path-comment-hook:

my-project/
├── src/
│   ├── main.py              # src/main.py
│   ├── utils/
│   │   ├── helpers.py       # src/utils/helpers.py
│   │   └── constants.py     # src/utils/constants.py
│   └── api/
│       ├── routes.py        # src/api/routes.py
│       └── models.py        # src/api/models.py
└── tests/
    ├── test_main.py         # tests/test_main.py
    └── test_utils.py        # tests/test_utils.py

Each file now has a clear path header making navigation effortless!

Need Help?