How to use

Collecting headers

To use, just run:

$ header-check
Warning: unknown extension ".rst" for file "./sphinx/install.rst"
Warning: unknown extension ".rst" for file "./sphinx/index.rst"
Warning: unknown extension ".rst" for file "./sphinx/usage.rst"
Warning: unknown extension ".rst" for file "./sphinx/license.rst"
Warning: unknown extension ".py" for file "./sphinx/conf.py"
Warning: unknown extension ".rst" for file "./sphinx/about.rst"
Ignored files saved to .header-check-more
You can add it to your .header-check
File "headers-ml.txt" generated
File "headers-sh.txt" generated

The execution with scan the current directory and sub-directories for files, extract headers from them and generate 3 reports :

headers-ml.txt for ML files
headers-cc.txt for C/C++ files
headers-sh.txt for SH files

You can then inspect these files to check all the headers present in the project. For each header, the header is displayed, with a unique ID (checksum) and a list of locations.

Typically, a report looks like:

Report on ML Header

Extracted headers

Header id: 5134d42449ef844bc30faac53a02511c
<<<
(**************************************************************************)
(*                                                                        *)
(*   Typerex Tools                                                        *)
(*                                                                        *)
(*   Copyright 2011-2017 OCamlPro SAS                                     *)
(*                                                                        *)
(*   All rights reserved.  This file is distributed under the terms of    *)
(*   the GNU General Public License version 3 described in the file       *)
(*   LICENSE.                                                             *)
(*                                                                        *)
(**************************************************************************)
>>>
File "./src/header-check/config.ml", line 0, characters 0-1:
Warning: file with 1 headers
File "./src/header-check/config.mli", line 0, characters 0-1:
Warning: file with 1 headers
File "./src/header-check/main.ml", line 0, characters 0-1:
Warning: file with 1 headers

For every header, an identifier is provided using a chechsum, the header is printed, and all the locations where it was found.

If you are happy, you can then clear temporary files:

$ header-check --clean
Removing file ".header-check-more"
Removing file "headers-ml.txt"
Removing file "headers-sh.txt"

Modifying headers

After inspection, you might want to add a default header to files with no header:

header-check --add-default HEADER_ID

Note that only files in the same category as the header can be modified (i.e. a ML header can only be added to ML files), so that you can specify this option for every category on the same command.

You might also want to replace some headers by other headers:

header-check --replace SRC_ID:DST_ID

will replace the source header SRC_ID by the destination header DST_ID. You may add directories if you want to restrict the substitution to these directories.

Since replacement must always be done using checksums, if you want to create a new header, you will need to insert it in a file, do a run to get its identifier, and then replace it.

If you want to replace multiple headers SRC1_ID, SRC2_ID, … by the same header DST_ID, you can also use:

header-check --replace-by DST_ID --from SRC1_ID --from SRC2_ID

Configuring a project

During the scan, header-check uses a default configuration to ignore or select files. You can extend this configuration using files .header-check in directories (their config will apply to where they are and their sub-directories). If the default configuration is wrong for you, you can use the option --empty to start with an empty configuration.

The format of .header-check is a list of lines starting with a command and a list of space-separated case-insensitive entries (comments can be introduced with # at the beginning of the line):

# files to ignore
IGNORE-FILES opam meta

# directories to ignore
IGNORE-DIRS _build .git .svn _opam

# extensions to ignore
IGNORE-EXT .cmx .cmo .mlt .md .toml

# headers to ignore
IGNORE-HEADERS fb748e994094746482684

# extensions for the ML files
ML-EXT .ml .mli .mll .mlp .ml4

# extensions for C/C++ files
CC-EXT .c .h .cpp .mly .js

# extensions for SH files
SH-EXT .sh .ac .in .m4

To check the default configuration, use:

header-check --show-config

Header formats

Headers are recognized as starting and ending with the same beginning of line:

(************************** for OCaml
/************************** for C-likes
########################### for shells

with internal char repeated at least 50 times.

Headers can be located anywhere in the file, so it may happens that comments with such beginning and ending are also recognize as headers.