NAME¶

reuse-annotate - Add REUSE information to files

SYNOPSIS¶

reuse annotate [options] [file ...]

DESCRIPTION¶

reuse-annotate adds REUSE information into the headers of files. This is useful especially in scenarios where you want to add a copyright holder or license to a lot of files without having to manually edit the header of each file.

WARNING:

The REUSE header is placed at the very top of the file, excepting certain existing headers like shebangs (#!) or XML declarations (<?xml version="1.0"?>). If a different header containing copyright or licensing information already exists in the file---at the top or elsewhere---that header is replaced in-place with the additionally supplied REUSE information.

The tool tries to auto-detect the comment style to use from the file extension of a file, and use that comment style.

Normally, the tool uses a single-line comment style when one is available (e.g., // is used instead of /* ... */ for C++ comment styles). If no single-line comment style is available, a multi-line style is used.

MANDATORY OPTIONS¶

At least one among the following options is required. They contain the information which the tool will add to the file(s).

OTHER OPTIONS¶

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

TEMPLATES¶

When the tool adds a header to a file, it normally first lists all copyright statements alphabetically, subsequently all contributors, then adds a single empty line, and finally lists all SPDX License Expressions alphabetically. 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:

In the future, more variables may be added.

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

AUTHOR¶

Free Software Foundation Europe

COPYRIGHT¶

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