headercheck

README

headercheck linter

headercheck checks and fixes required file headers across languages — configurable, Git-aware, CI-friendly, and golangci-lint compatible.

🦄 Features

• Validate headers: presence and formatting of file headers
• Autofix: insert or update headers in-place (--fix)
• Multiple header templates: matched at most once per file
• Binary-safe: ignore binary files by default; --force warns but continues
• Git-aware variables and change detection:
  • %author%: first committer name and email of the file (e.g., Jane Doe <jane@doe.com>)
  • %creation_date%: date of first commit touching the file (YYYY-MM-DD)
  • %last_update_date%: date of last commit touching the file (YYYY-MM-DD)
  • Don’t update headers in fix mode if file hasn’t changed since HEAD
• Flexible scoping: include/exclude by regex; defaults to popular source extensions
• Shebang-aware: keeps #!/usr/bin/env ... on top

🍸 GitHub Action

Use the reusable action published in this repository to run headercheck in CI:

# .github/workflows/headercheck.yml
name: Headercheck
on:
  push:
  pull_request:

jobs:
  headercheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run headercheck
        uses: samber/headercheck@v1
        with:
          # version: latest            # or v0.1.0, v0.2.3, ...
          # working-directory: .
          # config: .headercheck.yaml  # repeat with commas or newlines to pass multiple --config
          # templates: .header.txt     # repeat with commas or newlines to pass multiple --template
          # include: '(?i)\\.(go|ts|js)$'
          # exclude: 'vendor/|^third_party/'
          # paths: '.'                 # optional; defaults to repository root
          # fix: 'false'               # set to 'true' to modify files in-place
          # force: 'false'
          # verbose: 'false'

Notes:

• By default, headercheck expects a template at .header.txt, or you can configure templates via .headercheck.yaml or the action inputs.
• The action fails the job when issues are found (unless fix: 'true' is set).

🚀 Install binary

go install github.com/samber/headercheck/cmd/headercheck@latest

💡 Quick start

1. Create a header template at project root: .header.txt

// Copyright 2025 Example.
//
// Author: %author%
// Created: %creation_date%
// Last Update: %last_update_date%
// Project: My Awesome App

1. Run the linter:

headercheck ./...
# or to apply fixes
headercheck --fix ./...

By default, common source files are included. Use --include/--exclude to refine.

1. Review

--- a/examples/mixed/app/main.go
+++ b/examples/mixed/app/main.go
@@ -1,3 +1,9 @@
+// Copyright 2025 Example.
+//
+// Author: Jane Doe <jane@doe.com>
+// Created: 2025-08-10
+// Last Update: 2025-08-10
+// Project: My Awesome App
+
package main
 
func main() {

👀 Examples

The examples/ directory contains sample projects showing different configurations:

• examples/basic-go: minimal Go project with a single template for .go files.
  • Run: headercheck examples/basic-go (or --fix)
• examples/mixed: mixed repository with code, scripts, and YAML configs using three templates (.code.header.txt, .scripts.header.txt, .yaml.header.txt) and per-template include/exclude rules.
  • Run: headercheck examples/mixed (or --fix)

You can copy one of these into your project as a starting point and adapt the templates.

🛠️ Configuration (.headercheck.yaml)

At the repository root (or provide --config path):

# .headercheck.yaml
# List of template files (absolute or relative to repo root)
templates:
  - path: .header.txt
    include: (?i)\.(go|js|ts|tsx|jsx|rs|py|rb|php|java|kt|c|h|cpp|hpp|m|mm|swift|scala|sql|proto)$
    exclude: vendor/|^third_party/
  - path: .scripts.header.txt
    include: (?i)\.(sh|bash|zsh|ps1)$

CLI flags override config values:

• --config path: path to headercheck.yaml
• --template path[,path...]: add more templates (applies default include/exclude)
• --include regex, --exclude regex: default include/exclude applied to templates lacking their own
• --fix: apply changes
• --force: process invalid/binary files with a warning
• -v: verbose

🔌 golangci-lint integration

Two supported paths:

Module Plugin System (recommended)

Create .custom-gcl.yml in your repository that pulls headercheck as a plugin:

version: v2.0.0
plugins:
  - module: 'github.com/samber/headercheck'
    # version: v0.1.0 # pin your version

Build the custom binary:

golangci-lint custom
# produces ./custom-gcl

Then in .golangci.yml enable the linter:

version: "2"
linters:
  enable:
    - headercheck
linters-settings:
  custom:
    headercheck:
      description: Checks and fixes file headers
      original-url: github.com/samber/headercheck
      settings:
        template: .header.txt

Note: Depending on the GolangCI plugin strategy, you may run the headercheck CLI as a separate CI step, which is often simpler when linting non-Go files.

Go Plugin System

Alternatively build a .so plugin (requires CGO and exact dependency versions). See plugin/headercheck and GolangCI docs. The CLI remains the primary supported interface.

🤝 Contributing

• Ping me on Twitter @samuelberthe (DMs, mentions, whatever :))
• Fork the project
• Fix open issues or request new features

Don't hesitate ;)

👤 Contributors

💫 Show your support

Give a ⭐️ if this project helped you!

📝 License

Copyright © 2025 Samuel Berthe.

This project is Apache 2.0 licensed.