``add-license-headers`` setup
=============================

The ``add-license-headers`` hook adds and updates license headers in specified directories and
file types using `REUSE <https://reuse.software/>`_. Here is a sample license header for a
Python file generated by the template with a start year of 2023:

.. image:: /_static/images/license-header-light.png
   :class: only-light
   :alt: Picture of Python file's license header in light mode
   :width: 480px
   :align: center

.. image:: /_static/images/license-header-dark.PNG
   :class: only-dark
   :alt: Picture of Python file's license header in dark mode
   :width: 480px
   :align: center


To get started, add the hook to your ``.pre-commit-config.yaml`` file:

.. code:: yaml

  - repo: https://github.com/ansys/pre-commit-hooks
    rev: v0.5.2
    hooks:
    - id: add-license-headers

The hook runs on protocol buffer (PROTO) files in any directory, as well as Python files within
directories named ``src``, ``examples``, and ``tests``.

If your repository was created before the current year, add the ``--start_year`` argument with the
year that your first file was committed. The ``ansys-pre-commit-hooks`` repository started in 2023,
so the ``.pre-commit-config.yaml`` file looks like this:

.. code:: yaml

  - repo: https://github.com/ansys/pre-commit-hooks
    rev: v0.5.2
    hooks:
    - id: add-license-headers
      args:
      - --start_year=2023

By default, the
`ansys.jinja2 <https://github.com/ansys/pre-commit-hooks/blob/main/src/ansys/pre_commit_hooks/assets/.reuse/templates/ansys.jinja2>`_
template is used to generate the license headers for files.

The template contains the following variables:

- ``{{ copyright_line }}``: Contains the current year and the phrase
  "ANSYS, Inc. and/or its affiliates." by default.
- ``{{ expression }}``: Contains the SPDX-License-Identifier expression, which is "MIT" by default.

``add-license-headers`` hook arguments
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. list-table::
    :header-rows: 1
    :widths: 20 20 60
    :width: 100%

    * - Argument
      - Default value
      - Description
    * - ``--custom_copyright``
      - ``ANSYS, Inc. and/or its affiliates.``
      - Copyright line to include in the license header.
    * - ``--custom_template``
      - ``ansys``
      - Name of the ``.jinja2`` template file located in the ``.reuse/templates/`` directory.
    * - ``--custom_license``
      - ``MIT``
      - SPDX-License-Identifier expression to include in the license header. To view
        the list of valid SPDX license expressions, see the
        `SPDX License List <https://github.com/spdx/license-list-data/tree/main/text>`_.
    * - ``--start_year``
      - ``2023``
      - Year that the first file was committed to the repository.
    * - ``--ignore_license_check``
      - ``False``
      - Whether to check for the license in the header.

.. include:: faq.rst

.. include:: issues-limitations.rst

.. toctree::
   :hidden:
   :maxdepth: 3

   faq
   issues-limitations