codestamp 0.2.0

CLI tool to manage copyright headers in source-code files

codestamp

Stamp and manage copyright headers across your source-code files.

Built by Medhavee Inc · Author Shardul Kulkarni

---

Installation

pip install codestamp

Or for local development:

git clone https://github.com/yourusername/codestamp
cd codestamp
pip install -r requirements-dev.txt
pip install -e .

---

Quick start

1. Create a license.txt in your project root whose first line is your copyright statement:

Copyright (c) 2026 Medhavee Inc. All rights reserved. Proprietary and confidential.

2. Run from the project root:

# Add headers to files changed in the last git commit (CI-friendly default)
codestamp

# Add headers to ALL source files in the tree
codestamp --bulk

# Add headers to staged files only
codestamp --staged

# Skip specific files or directories using an exclusion file
codestamp --bulk --exclude .csignore

# Preview without writing anything
codestamp --bulk --dry-run

# Update every file's copyright to a new statement
codestamp update "Copyright (c) 2026 Medhavee Foundation. All rights reserved."

# See all supported file types
codestamp list-types

---

Commands

Command	Description
codestamp	Process files added/modified in the last git commit (default)
codestamp --bulk	Process all source files in the project tree
codestamp --staged	Process only currently git-staged files
codestamp --dry-run	Preview all actions without writing any files
codestamp update "<text>"	Replace old copyright header with new text everywhere
codestamp list-types	Show all supported file extensions and comment styles

Options

Flag	Default	Description
--license <path>	license.txt	Custom path to your license/copyright file
--exclude <path>	(none)	Path to an exclusion file (see below)
--dry-run	off	Preview mode — no files are written

---

Excluding files and directories

Pass --exclude <file> to point codestamp at a plain-text exclusion list. Each line can be a file path, a directory, a glob pattern, or a comment:

# .csignore  — paths codestamp should never touch

# Third-party files
vendor/google_utils.py
lib/react_helpers.js

# Entire directories
vendor/
third_party/
node_modules/

# Glob patterns
*.min.js
*.generated.py

Then run:

codestamp --bulk --exclude .csignore

Rules supported per line:

Pattern	Matches
vendor/lib.py	Exact file path
vendor/ or vendor	Any file inside that directory
*.min.js	Glob matched against the full file path
# comment	Ignored
(blank line)	Ignored

---

Output & status codes

Every file processed is reported with a status icon:

Icon	Status	Meaning
✅	ADDED	Copyright header successfully stamped
🔄	UPDATED	Existing header replaced with new text
⏭	SKIPPED	File already has your copyright — left untouched
➖	UNSUPPORTED	File extension not recognised
❌	ERROR	Could not read or write the file

---

Supported file types

Style	Extensions
# comment	.py .sh .bash .zsh .rb .pl .r .yaml .yml .toml .conf .tf .tfvars
// comment	.js .ts .jsx .tsx .java .go .swift .kt .kts .rs .cs .cpp .cc .c .h .hpp .dart .scala .groovy .php
/* comment */	.css .scss .less
<!-- comment -->	.html .svelte .vue .xml .svg

Run codestamp list-types to see the full up-to-date list.

---

How headers are inserted

• Shebang lines (#!/usr/bin/env python3) are always respected — the header is inserted on line 2, never before the shebang.
• Files that already contain your copyright text are silently skipped.
• The update command rewrites license.txt with the new header text after updating all files.

---

Git integration

The default mode (no flags) processes files from the last commit, making it a perfect fit for CI pipelines:

# .github/workflows/copyright.yml
name: Copyright Headers

on: [push]

jobs:
  stamp:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2       # needed so HEAD~1 diff works

      - name: Install codestamp
        run: pip install codestamp

      - name: Stamp new files
        run: |
          codestamp --exclude .csignore
          git diff --quiet || (
            git config user.email "bot@ci"
            git config user.name "CI Bot"
            git commit -am "chore: add copyright headers"
            git push
          )

---

Contributing

git clone https://github.com/yourusername/codestamp
cd codestamp
pip install -r requirements-dev.txt
pip install -e .
pytest

Pull requests are welcome! Please open an issue first for larger changes.

---

License

MIT © Shardul Kulkarni / Medhavee Inc