REUSE-ANNOTATE(1)

💖 reuse-annotate(1) — the reuse girlies' guide to auto-annotating ur files ✨

okay so real talk, bestie: this is reuse-annotate, straight out of the reuse manual, section 1. she's a little command that slides REUSE info into ur file headers and honestly? she ate. 🎀

---

🌸 NAME 🌸

reuse-annotate — adds REUSE information to files 💅

---

🦋 SYNOPSIS 🦋

reuse annotate [options] [file ...]

---

✨ DESCRIPTION ✨

okay so reuse-annotate literally just adds REUSE information into the headers of files. and like, it's giving main character energy when you wanna slap a copyright holder or a license onto a whole pile of files without manually editing every single header by hand. no cap, that's the whole vibe. 💖

⚠️ WARNING, bestie, listen to me: be cautious with using annotate in automated processes. like, nothing is stopping you from using it in your release script — nothing!! — but you should make sure the information it adds is actually reflective of reality. and the best way to verify that? manually. 🙈 periodt.

the REUSE header goes at the very top of the file, except when there are certain existing headers like shebangs (#!) or XML declarations (<?xml version="1.0"?>). those get to stay, they're iconic. ✨

and if a different header that already contains copyright or licensing info exists in the file — top or literally anywhere else — that header gets replaced in-place with the additionally supplied REUSE information. slay.

the tool tries to auto-detect the comment style to use from the file extension of a file, and then uses that comment style. iykyk. 💫

normally, the tool uses a single-line comment style when one is available (e.g. // is used instead of /* ... */ for C++ comment styles — she has preferences). if no single-line comment style is available, a multi-line style is used. simple as that. 🫶

---

👑 MANDATORY OPTIONS 👑

at least one among the following options is required — like, you cannot skip this part. they contain the information which the tool will add to the file(s). and you can repeat these options as many times as your heart desires. 💜

• -c, --copyright COPYRIGHT — a copyright holder. this does not contain the year or the copyright prefix — check --year and --copyright-prefix for those, bestie. 🎀
• -l, --license LICENSE — an SPDX license identifier. 💅
• --contributor CONTRIBUTOR — a name of a contributor. the contributor will be added via the SPDX-FileContributor: tag. 🦋

---

🌈 OTHER OPTIONS 🌈

• -y, --year YEAR — define the year of the copyright notice(s). if not defined, the year defaults to the current year. the value may be a (complex) range, such as '2017-2019', or '2017, 2019-2022, 2024-Present'. yes she can handle all that, she's talented. ⭐
• -s, --style STYLE — override the comment style detection mechanism to force a comment style on the files. this is useful when a file extension is not recognised, or when a file extension is associated with a comment style that you disagree with (it happens, we've all been there 💀).
• --copyright-prefix PREFIX — the prefix to use in the copyright notice. if not defined, spdx is used as prefix. the available copyright prefixes are:

spdx:               SPDX-FileCopyrightText: <year> <author>
spdx-c:             SPDX-FileCopyrightText: (C) <year> <author>
spdx-symbol:        SPDX-FileCopyrightText: © <year> <author>
spdx-string:        SPDX-FileCopyrightText: Copyright <year> <author>
spdx-string-c:      SPDX-FileCopyrightText: Copyright (C) <year> <author>
spdx-string-symbol: SPDX-FileCopyrightText: Copyright © <year> <author>
string:             Copyright <year> <author>
string-c:           Copyright (C) <year> <author>
string-symbol:      Copyright © <year> <author>
symbol:             © <year> <author>

• -t, --template TEMPLATE — the template to use for the comment header. the template name match the name of the template in .reuse/templates/, without the .jinja2 or .commented.jinja2 suffix. 🧚
• --exclude-year — do not include the year in the copyright notice. bye year, you're not invited. 👋
• --merge-copyrights — if two (or more) copyright notices are identical except for their years, output them as a single line with the years combined. efficiency queen. 🔥
• --single-line — force the tool to use a single-line comment style. for C, this would be //. 💫
• --multi-line — force the tool to use a multi-line comment style. for C, this would be /* ... */. ✨
• -r, --recursive — annotate all files recursively under the specified path. go off, dig into every folder. 🕵️‍♀️
• --no-replace — instead of replacing the first header in the file which contains copyright and licensing information, keep it and create a new header at the top. respectful. 🫶
• --force-dot-license — always write a .license file instead of trying to write into the file itself. 🎀
• --fallback-dot-license — instead of aborting when a file extension does not have an associated comment style, create a .license file for those files. no drama, just solutions. 💖
• --skip-unrecognised — instead of aborting when a file extension does not have an associated comment style, skip those files. we move on. 💅
• --help — display help and exit. the classic. 👑

---

🧚 TEMPLATES 🧚

when the tool adds a header to a file, it normally first lists all copyright notices alphabetically, subsequently all contributors, then adds a single empty line, and finally lists all SPDX License Expressions alphabetically. okay, organized queen. 💅

but bestie, it is possible to change this behaviour and use a custom type of header that contains extra text. this is done through Jinja2 templates. ✨

the default template is:

{% for copyright_line in copyright_lines %}
{{ copyright_line }}
{% endfor %}
{% for contributor_line in contributor_lines %}
SPDX-FileContributor: {{ contributor_line }}
{% endfor %}

{% for expression in spdx_expressions %}
SPDX-License-Identifier: {{ expression }}
{% endfor %}

templates are automatically commented by the tool, depending on the detected or specified comment style. 🎀

you can create your own Jinja2 templates and place them in .reuse/templates/. you must suffix your template with .jinja2. 🦋

inside of the template, you have access to the following variables:

• copyright_lines — a list of copyright notices (string).
• contributor_lines — a list of contributors (string).
• spdx_expressions — a list of SPDX License Expressions (string).

in the future, more variables may be added. we love growth. 🌱

in some cases, you might want to do custom comment formatting. in those cases, you can pre-format your header as a comment. when doing so, suffix your template with .commented.jinja2. 💫

an example of a custom template with manual commenting is:

/*
{% for copyright_line in copyright_lines %}
 * {{ copyright_line }}
{% endfor %}
{% if copyright_lines and spdx_expressions %}
 *
{% endif %}
{% for expression in spdx_expressions %}
 * SPDX-License-Identifier: {{ expression }}
{% endfor %}
{% if "GPL-3.0-or-later" in spdx_expressions %}
 *
 * This program is free software: you can redistribute it and/or modify it under
 * the terms of the GNU General Public License as published by the Free Software
 * Foundation, either version 3 of the License, or (at your option) any later
 * version.
 *
 * This program is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along with
 * this program. If not, see <https://www.gnu.org/licenses/>.
{% endif %}
 */

---

🍓 EXAMPLES 🍓

the basic usage is reuse annotate --copyright="Jane Doe" --license=MIT my_file.py. this will add the following header to the file (assuming that the current year is 2019):

# SPDX-FileCopyrightText: 2019 Jane Doe
#
# SPDX-License-Identifier: MIT

look at that. chef's kiss. 😭💖

---

💜 AUTHOR 💜

Free Software Foundation Europe — icons only. 👑

---

🎀 COPYRIGHT 🎀

2026, Free Software Foundation Europe. CC-BY-SA-4.0

---

and that's the whole page, bestie!! this edition of the reuse manual is version 6.2.0, dated Jul 16, 2026 — she's fresh, she's current, she's iconic. go annotate something. 💅✨🦋