autoheader 9.0.8

Enterprise-grade file header tool that injects repo-relative path headers into Python files

autoheader

autoheader is an enterprise-grade CLI tool for source code projects that automatically adds or refreshes file headers containing each file's repo-relative path.
This helps developers quickly identify file origins, improves navigation in large codebases, and standardizes file structure across teams.

Example of what autoheader produces:

# src/utils/parser.py

from __future__ import annotations
...

// src/api/client.js

import { fetch } from 'node-fetch';
...

Perfect for monorepos, multi-module architectures, enterprise codebases, and any project where file traceability matters.

✅ Features

• 🌐 Polyglot Support: Manages headers for Python, JavaScript, Go, CSS, and any other language via a simple TOML configuration.
• ⚡ Rich UX: Beautiful, modern output with emojis, progress bars, and a formatted help screen (powered by Rich).
• 👁️ Visual Diffs: See exactly what will change with side-by-side diffs during dry-runs.
• 🧠 Smart Copyright: Automatically updates year ranges (e.g., 2020-2025) in existing headers instead of overwriting them.
• 🚀 Performance: Supports passing specific files for blazing fast execution in pre-commit hooks.
• ⚙️ Smart Setup: Get started in seconds with autoheader --init to generate a default configuration file.
• 📂 Team Configuration: Centralize settings for your whole team using autoheader.toml or a remote config URL.
• 🛡️ Pre-commit Integration: Automatically enforce headers on every commit with autoheader --check.
• 🤖 Auto-Installer: Get started in seconds with autoheader --install-precommit.
• Smart Filtering:
  • .gitignore Aware: Automatically respects all patterns in your project's .gitignore file.
  • Inline Ignores: Skip any file by adding autoheader: ignore anywhere in its content.
  • Robust Excludes: Includes a depth guard (--depth) and a robust exclusion system (--exclude).
• Idempotent & Safe: Runs repeatedly with no duplicates. Dry-run by default.
• Flexible Modes: Supports --override (for refactoring), --remove (for cleanup), and --backup (for safety).
• CI-Friendly: Full support for --yes and --quiet flags for non-interactive environments.
• Automatic Root Detection: Uses project markers (pyproject.toml, README.md, .gitignore) to confirm safe execution.

📦 Installation

Install from PyPI:

pip install "autoheader[precommit]"

• The [precommit] extra installs pyyaml, which is required for the autoheader --install-precommit command.
• rich-argparse is now a direct dependency and will be installed automatically.

Or install the latest version directly from source:

pip install git+https://github.com/dhruv13x/autoheader

🚀 Quick Start

Step 1: Generate a Configuration

The easiest way to get started is to generate a default autoheader.toml configuration file. This file is pre-configured for Python projects and contains all available settings.

autoheader --init

✅ Created default config at /path/to/project/autoheader.toml.

Step 2: Run a Dry-Run

Run autoheader to see a preview of the changes. The tool will scan your project and show a visual diff of any headers that need to be added, updated, or removed.

autoheader

Step 3. Apply Changes

To apply changes to your files for real, use --no-dry-run:

autoheader --no-dry-run

🛡️ Pre-commit & CI Mode

autoheader is built for modern CI/CD and pre-commit workflows.

1. autoheader --check

The --check flag runs autoheader in a dry-run mode. If any files need headers added, removed, or overridden, it will print the files and exit with code 1, failing your CI or pre-commit hook.

This is the engine that enforces header consistency.

2. autoheader --install-precommit

This is the easiest way to get started. It automatically finds your .pre-commit-config.yaml (or creates one) and adds autoheader as a local hook.

Requires pyyaml: You must run pip install "autoheader[precommit]" first.

# 1. Install with pre-commit support
pip install "autoheader[precommit]"

# 2. Add autoheader to your .pre-commit-config.yaml
autoheader --install-precommit

# 3. Activate the hook
pre-commit install

Now, autoheader --check will run automatically on every commit.

3. Manual Pre-commit Config

You can also add autoheader as a remote hook. For a multi-language project, we recommend specifying types_or to run on all configured file types.

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

- repo: https://github.com/dhruv13x/autoheader
  rev: v9.0.7  # <-- Use the latest version
  hooks:
    - id: autoheader
      name: autoheader file header checker
      # Run on any file type you have configured in autoheader.toml
      types_or: [python, javascript]

📂 Enterprise Configuration (autoheader.toml)

For teams, you can stop passing CLI flags and standardize settings in an autoheader.toml file at your project's root.

Precedence: CLI arguments > autoheader.toml settings > Application defaults.

Run autoheader --init to generate a file pre-filled with the defaults, which looks like this:

# autoheader configuration file
# Generated by `autoheader --init`
# For more info, see: https://github.com/dhruv13x/autoheader

[general]
# Create .bak files before modifying. (Default: false)
backup = false

# Number of parallel workers. (Default: 8)
workers = 8

# auto-confirm all prompts (e.g., for CI). (Default: false)
# yes = false

[detection]
# Max directory depth to scan. (Default: no limit)
# depth = 10

# Files that mark the project root.
markers = [
    ".gitignore",
    "README.md",
    "README.rst",
    "pyproject.toml",
]

[exclude]
# Extra paths/globs to exclude.
# The built-in defaults are included below for convenience.
# Note: .gitignore patterns are also automatically included.
paths = [
    ".git",
    ".github",
    ".hg",
    ".mypy_cache",
    ".pytest_cache",
    ".ruff_cache",
    ".svn",
    ".venv",
    "__pycache__",
    "build",
    "dist",
    "env",
    "node_modules",
    "venv",
]

# This legacy section is used for the global `blank_lines_after` setting.
[header]
blank_lines_after = 1

# --- Language-Specific Configuration ---
# autoheader v2.0+ uses language blocks.
# The default config for Python is shown below.
# You can add more, e.g., [language.javascript], [language.go], etc.

[language.python]
# Globs to identify files for this language
file_globs = [
    "*.py",
    "*.pyi",
]

# The comment prefix to use
prefix = "# "

# The template for the header line. {path} is the placeholder.
template = "# {path}"

# Whether to check for shebangs/encoding (Python-specific)
check_encoding = true

Example: Adding JavaScript Support

To add support for JavaScript, simply add another language block:

[language.javascript]
file_globs = ["*.js", "*.jsx", "*.ts"]
prefix = "// "
template = "// {path}"
check_encoding = false  # No shebangs to worry about

📘 Advanced Usage & CLI Arguments

autoheader offers a rich set of CLI arguments to customize its behavior. Arguments are grouped by function for clarity.

Argument	Description	Default
Main Actions
files	Specific files to process. If not provided, scans the root directory.	(scan all)
-d, --dry-run	Do not write changes (default).	True
-nd, --no-dry-run	Apply changes to files.	False
--override	Rewrite existing header lines to fresh, correct ones.	False
--remove	Remove all autoheader lines from files.	False
CI / Pre-commit / Init
--check	Exit with code 1 if any file needs header changes (for pre-commit/CI).	False
--check-hash	Verify file integrity by checking content hash in headers.	False
--init	Create a default autoheader.toml in the current directory.	False
--install-precommit	Install autoheader as a 'repo: local' pre-commit hook.	False
General Behavior
-y, --yes	Assume yes to all confirmation prompts.	False
--backup	Create .bak backups before writing.	False
--root	Root directory.	Current dir
--workers	Number of parallel workers to use.	8
--timeout	Timeout in seconds for processing a single file.	60.0
--config-url	URL to fetch remote configuration from.	None
--clear-cache	Clear the cache before running.	False
Filtering & Discovery
--depth	Max directory depth from root (e.g., 3).	None
--exclude	Extra glob(s) to exclude (can repeat).	[]
--markers	Project root markers (overrides TOML and defaults).	['.gitignore', 'README.md', 'README.rst', 'pyproject.toml']
Header Customization (from TOML)
--blank-lines-after	Number of blank lines to add after the header.	1
Output Styling
-v, --verbose	Increase verbosity. (use -vv for more).	0
-q, --quiet	Suppress informational output; only show errors.	False
--no-color	Disable colored output.	False
--no-emoji	Disable emoji prefixes.	False
--format	Output format. (default or sarif)	default

Ignore Specific Files

To exclude a single file without adding it to autoheader.toml or .gitignore, add a magic comment anywhere in the file's content:

# autoheader: ignore

autoheader will see this and skip the file.

📂 Example Output

autoheader provides clear, aligned, and color-coded output.

Project root confirmed (3 markers found).
Planning changes for /path/to/my-project...
[progress bar]
Plan complete. Found 42 files.
Applying changes to 5 files using 8 workers...
✅ ADD              src/autoheader/app.py
⚠️ OVERRIDE         src/autoheader/cli.py
│  Header diff for src/autoheader/cli.py
│  - # old_header
│  + # src/autoheader/cli.py
❌ REMOVE           src/autoheader/old_util.py
🔵 SKIP             src/autoheader/models.py
⚫ SKIP_EXCLUDED    .venv/lib/python3.11/site-packages/rich/console.py
🔥 ERROR            Failed to process src/autoheader/locked_file.py: [Errno 13] Permission denied

Summary: added=1, overridden=1, removed=1, skipped_ok=34, skipped_excluded=5.
NOTE: this was a dry run. Use --no-dry-run to apply changes.

✨ Done in 0.42s.

🛡 Safety & Guarantees

autoheader is built with enterprise safety in mind:

• Dry-run by default.
• Never touches files without your explicit --no-dry-run.
• .gitignore Aware: Automatically respects your project's .gitignore rules.
• Root Detection: Confirms it's running in a project root before starting.
• Interactive Prompts: Prompts for confirmation before making changes (unless --yes is used).
• Safe by Default: Warns you if you run without --backup.
• Resource Safe: Includes a file size limit to avoid parsing huge files.
• Safe Traversal: Skips symlinks to prevent unexpected behavior.
• Preserves Permissions: Keeps original file permissions on write.

🔧 Development

Install in editable mode with all dev and pre-commit dependencies:

git clone https://github.com/dhruv13x/autoheader
cd autoheader
pip install -e ".[dev,precommit]"

Run tests:

pytest

Run linter & formatter:

ruff check .
black .

🗺️ Roadmap

autoheader is actively developed. Here's a look at what's planned for the future:

• Standardization & Ecosystem (v5.0+):
  • Native SPDX License Support: Integrate the SPDX license database to automatically generate legally compliant header blocks.
  • Native Git Hook Installer: Remove the dependency on the pre-commit framework for simpler use cases.
  • LSP (Language Server) Integration: Highlight missing headers directly in your IDE as you type.

For more details, see the full Public Roadmap.

🤝 Contributing

Pull requests are welcome. If proposing large changes, open an issue first to discuss design and approach.

🐛 Reporting Issues

Please open issues here:
https://github.com/dhruv13x/autoheader/issues

Include:

• What command you ran
• Error output
• Your Python version
• OS / environment information

📜 License

MIT © dhruv13x

⭐ Support the Project

If this tool helped you, consider giving the repo a star:
https://github.com/dhruv13x/autoheader

Stars help visibility and future development!