# add header comment
A [pre-commit](https://pre-commit.com) hook to automatically add or update a header of a text file with the appropriate comment style for your source code.
## Why does this exist?
This exists so that you can include a license (or any other piece of text) at the top of a lot of different files, and it can automatically update them all at once.
There are already other pre-commit hooks that do this (such as [Lucas-C/pre-commit-hooks](https://github.com/Lucas-C/pre-commit-hooks)), how does this one differ?
This pre-commit hook
- Always keeps your header up to date when you change the header text.
- It does not rely on an fuzzy string matching or require you to remove all the old headers with a separate command before applying the new header.
- Instead, it looks for the end of the comment or a custom string that you set to identify the end of the header.
- Has the ability to wrap long text onto a new line. This is not as useful for just pasting a license at the top of a file that is already formatted with newlines, but quite useful if the block of text is just a long single line.
## How to use?
This is how to set up the pre-commit hook. You may consider running the hook multiple times for different file extensions. Related, you should change the files regex and name (to help better identify each check) appropriately. And you can pass any of the [below options](#options) in the `args` section.
```yaml
repos:
- repo: https://github.com/sayari-analytics/add-header-comment
rev: v1.0.1
hooks:
- id: add-header
name: Add or update header for Python files
args:
- --header-filepath
- path/to/header.txt
# put optional arguments here
files: \.py$
```
## Options
These are the options that the script accepts. This is mostly copied from the output of the `--help` option.
One thing to note is that the filepaths you want this script to run on are passed as positional arguments. In a pre-commit hook, this is handled automatically. Something to keep note of if you are using this outside of pre-commit.
- `--header-filepath` (required, string) - The filepath to the header file.
- `--comment-style` (optional, string) - A single comment prefix or a triplet separated by vertical bars (`<comment-start>|<comment-prefix>|<comment-end>`). E.g., a Java comment block would be: `/*| *| */`. Defaults to `#`.
- `--newline-after-comment-start` (optional, boolean flag) - Adds a newline after the comment start.
- `--newline-before-comment-end` (optional, boolean flag) - Adds a newline before the comment end.
- `--start-header-after` (optional, string) - A string to search for to start the header afterwards. Helpful if you want to add a header to a shell script.
- `--ignore-below-string` (optional, string) - A string to search for to determine where the header stops and the rest of the content starts (typically in a comment). Defaults to `ignore below`.
- `--stop-at-ignore-below` (optional, boolean flag) - Stops adding the header when the ignore-below-string is found.
- `--max-line-length` (optional, integer) - Splits lines by word tokens that are longer than the specified length.
- `--fail-on-fix` (optional, boolean flag) - Exits with a non-zero status if any files were modified. No need to pass this when using as a pre-commit hook since pre-commit will fail if any files have been modified.
## Other ways to install
If you prefer to use this tool without pre-commit, you can install the standalone Python package.
```bash
pip install add-header-comment
```
After installing the package, you can use the cli tool by typing:
```bash
# with the installed console script entry point
add-header-comment -h
# or the use the alias
add-header -h
# or through the Python module
python -m add_header_comment -h
```
## Examples
Here are some examples demonstrating this pre-commit hook's ability. Additionally, you might find it helpful to look at our [test cases](./tests/) for more examples.
### Markdown with entirely different header
The command to run:
```bash
add-header \
--header-filepath path/to/header.txt \
--comment-style "<!--||-->" \
filepath1.md filepath2.md
```
If the existing header is like this:
```markdown
<!-- There is no common text between this old header and the new one -->
# Hello World
```
Outputs a header like this (there is no fuzzy string matching or running a separate command to remove the old header required):
```markdown
<!-- This is the new header comment -->
# Hello World
```
### Java with max line length and newline before comment end
The command to run:
```bash
add-header \
--header-filepath path/to/header.txt \
--comment-style "/*| *| */" \
--newline-before-comment-end \
--max-line-length 110 \
filepath1.java filepath2.java
```
Outputs a header like this:
```java
/* This is a really long comment that should get split after 110 characters. This is a really long comment
* that should get split after 110 characters.
*/
public class HelloWorld {}
```
### Java without max line length and without newline before comment end
The command to run:
```bash
add-header \
--header-filepath path/to/header.txt \
--comment-style "/*| *| */" \
filepath1.java filepath2.java
```
Outputs a header like this:
```java
/* This is a really long comment that does not get get split. This is a really long comment that does not get get split. */
public class HelloWorld {}
```
### Bash
The command to run:
```bash
add-header \
--header-filepath path/to/header.txt \
--start-header-after "#!/bin/bash" \
filepath1.sh filepath2.sh
```
Outputs a header like this:
```bash
#!/bin/bash
# this is the header comment
echo hi
```
### JavaScript
The command to run:
```bash
add-header \
--header-filepath path/to/header.txt \
--comment-style "//" \
filepath1.js filepath2.js
```
Outputs a header like this:
```js
// this is the header comment
console.log('hi')
```
### Python with additional file specific custom header
The command to run:
```bash
add-header \
--header-filepath path/to/header.txt \
--stop-at-ignore-below \
filepath1.py filepath2.py
```
Outputs a header like this:
```py
# this is the header comment
# this is another line of the header comment
# header ends here, ignore below
# This is a custom comment at the top of the file that is not modified by the pre-commit hook
import os
```
Raw data
{
"_id": null,
"home_page": "https://github.com/sayari-analytics/add-header-comment",
"name": "add-header-comment",
"maintainer": "Sayari Labs",
"docs_url": null,
"requires_python": ">=3.5",
"maintainer_email": null,
"keywords": "pre-commit, file header, license, automation",
"author": "Nathaniel Young",
"author_email": "nyoung@sayari.com",
"download_url": "https://files.pythonhosted.org/packages/95/1d/101cc164835428d639b9fc889aecdf99d9658bcf9af128ae2723f88d8997/add_header_comment-1.0.1.tar.gz",
"platform": null,
"description": "# add header comment\n\nA [pre-commit](https://pre-commit.com) hook to automatically add or update a header of a text file with the appropriate comment style for your source code.\n\n## Why does this exist?\n\nThis exists so that you can include a license (or any other piece of text) at the top of a lot of different files, and it can automatically update them all at once.\n\nThere are already other pre-commit hooks that do this (such as [Lucas-C/pre-commit-hooks](https://github.com/Lucas-C/pre-commit-hooks)), how does this one differ?\n\nThis pre-commit hook\n\n- Always keeps your header up to date when you change the header text.\n - It does not rely on an fuzzy string matching or require you to remove all the old headers with a separate command before applying the new header.\n - Instead, it looks for the end of the comment or a custom string that you set to identify the end of the header.\n- Has the ability to wrap long text onto a new line. This is not as useful for just pasting a license at the top of a file that is already formatted with newlines, but quite useful if the block of text is just a long single line.\n\n## How to use?\n\nThis is how to set up the pre-commit hook. You may consider running the hook multiple times for different file extensions. Related, you should change the files regex and name (to help better identify each check) appropriately. And you can pass any of the [below options](#options) in the `args` section.\n\n```yaml\nrepos:\n - repo: https://github.com/sayari-analytics/add-header-comment\n rev: v1.0.1\n hooks:\n - id: add-header\n name: Add or update header for Python files\n args:\n - --header-filepath\n - path/to/header.txt\n # put optional arguments here\n files: \\.py$\n```\n\n## Options\n\nThese are the options that the script accepts. This is mostly copied from the output of the `--help` option.\n\nOne thing to note is that the filepaths you want this script to run on are passed as positional arguments. In a pre-commit hook, this is handled automatically. Something to keep note of if you are using this outside of pre-commit.\n\n- `--header-filepath` (required, string) - The filepath to the header file.\n- `--comment-style` (optional, string) - A single comment prefix or a triplet separated by vertical bars (`<comment-start>|<comment-prefix>|<comment-end>`). E.g., a Java comment block would be: `/*| *| */`. Defaults to `#`.\n- `--newline-after-comment-start` (optional, boolean flag) - Adds a newline after the comment start.\n- `--newline-before-comment-end` (optional, boolean flag) - Adds a newline before the comment end.\n- `--start-header-after` (optional, string) - A string to search for to start the header afterwards. Helpful if you want to add a header to a shell script.\n- `--ignore-below-string` (optional, string) - A string to search for to determine where the header stops and the rest of the content starts (typically in a comment). Defaults to `ignore below`.\n- `--stop-at-ignore-below` (optional, boolean flag) - Stops adding the header when the ignore-below-string is found.\n- `--max-line-length` (optional, integer) - Splits lines by word tokens that are longer than the specified length.\n- `--fail-on-fix` (optional, boolean flag) - Exits with a non-zero status if any files were modified. No need to pass this when using as a pre-commit hook since pre-commit will fail if any files have been modified.\n\n## Other ways to install\n\nIf you prefer to use this tool without pre-commit, you can install the standalone Python package.\n\n```bash\npip install add-header-comment\n```\n\nAfter installing the package, you can use the cli tool by typing:\n\n```bash\n# with the installed console script entry point\nadd-header-comment -h\n# or the use the alias\nadd-header -h\n# or through the Python module\npython -m add_header_comment -h\n```\n\n## Examples\n\nHere are some examples demonstrating this pre-commit hook's ability. Additionally, you might find it helpful to look at our [test cases](./tests/) for more examples.\n\n### Markdown with entirely different header\n\nThe command to run:\n\n```bash\nadd-header \\\n --header-filepath path/to/header.txt \\\n --comment-style \"<!--||-->\" \\\n filepath1.md filepath2.md\n```\n\nIf the existing header is like this:\n\n```markdown\n<!-- There is no common text between this old header and the new one -->\n# Hello World\n```\n\nOutputs a header like this (there is no fuzzy string matching or running a separate command to remove the old header required):\n\n```markdown\n<!-- This is the new header comment -->\n# Hello World\n```\n\n### Java with max line length and newline before comment end\n\nThe command to run:\n\n```bash\nadd-header \\\n --header-filepath path/to/header.txt \\\n --comment-style \"/*| *| */\" \\\n --newline-before-comment-end \\\n --max-line-length 110 \\\n filepath1.java filepath2.java\n```\n\nOutputs a header like this:\n\n```java\n/* This is a really long comment that should get split after 110 characters. This is a really long comment\n * that should get split after 110 characters.\n */\npublic class HelloWorld {}\n```\n\n### Java without max line length and without newline before comment end\n\nThe command to run:\n\n```bash\nadd-header \\\n --header-filepath path/to/header.txt \\\n --comment-style \"/*| *| */\" \\\n filepath1.java filepath2.java\n```\n\nOutputs a header like this:\n\n```java\n/* This is a really long comment that does not get get split. This is a really long comment that does not get get split. */\npublic class HelloWorld {}\n```\n\n### Bash\n\nThe command to run:\n\n```bash\nadd-header \\\n --header-filepath path/to/header.txt \\\n --start-header-after \"#!/bin/bash\" \\\n filepath1.sh filepath2.sh\n```\n\nOutputs a header like this:\n\n```bash\n#!/bin/bash\n# this is the header comment\necho hi\n```\n\n### JavaScript\n\nThe command to run:\n\n```bash\nadd-header \\\n --header-filepath path/to/header.txt \\\n --comment-style \"//\" \\\n filepath1.js filepath2.js\n```\n\nOutputs a header like this:\n\n```js\n// this is the header comment\nconsole.log('hi')\n```\n\n### Python with additional file specific custom header\n\nThe command to run:\n\n```bash\nadd-header \\\n --header-filepath path/to/header.txt \\\n --stop-at-ignore-below \\\n filepath1.py filepath2.py\n```\n\nOutputs a header like this:\n\n```py\n# this is the header comment\n# this is another line of the header comment\n# header ends here, ignore below\n# This is a custom comment at the top of the file that is not modified by the pre-commit hook\nimport os\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Add or update the header of a file with the appropriate comment style.",
"version": "1.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/sayari-analytics/add-header-comment/issues",
"Homepage": "https://github.com/sayari-analytics/add-header-comment",
"Source Code": "https://github.com/sayari-analytics/add-header-comment"
},
"split_keywords": [
"pre-commit",
" file header",
" license",
" automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "bd7ce46e19f3b0186f34fdcb2450c3a16b22fbe627de9ca3b3fe3f2c509f696b",
"md5": "0eaa62076c939b5305c05bb260acfdf4",
"sha256": "851157022b5f5295bd90c1bfda4736ec86255fe3a495ff0463db6e9e22dc52c6"
},
"downloads": -1,
"filename": "add_header_comment-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0eaa62076c939b5305c05bb260acfdf4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.5",
"size": 7286,
"upload_time": "2025-07-11T05:01:23",
"upload_time_iso_8601": "2025-07-11T05:01:23.656861Z",
"url": "https://files.pythonhosted.org/packages/bd/7c/e46e19f3b0186f34fdcb2450c3a16b22fbe627de9ca3b3fe3f2c509f696b/add_header_comment-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "951d101cc164835428d639b9fc889aecdf99d9658bcf9af128ae2723f88d8997",
"md5": "5070f7b8792d8c5b332b0c260cda98ea",
"sha256": "8702519af634c134d1ee77f91a6cfdf005876bd971d92ab05708e573982b7398"
},
"downloads": -1,
"filename": "add_header_comment-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "5070f7b8792d8c5b332b0c260cda98ea",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5",
"size": 6918,
"upload_time": "2025-07-11T05:01:24",
"upload_time_iso_8601": "2025-07-11T05:01:24.478863Z",
"url": "https://files.pythonhosted.org/packages/95/1d/101cc164835428d639b9fc889aecdf99d9658bcf9af128ae2723f88d8997/add_header_comment-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-11 05:01:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sayari-analytics",
"github_project": "add-header-comment",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "add-header-comment"
}
JSON
