SERiF/commit-config/hooks/README.md

# Hook for adding and maintaing file headers automatically
All 4DSSE files should have a header specifying authors, last edits, copyright, and liscence information. 

Hook should be setup automatically to run on each commit. 

## Dependencies
- GitPython
- Python (>=3.10)

## Installation
Generally one is intended to use this by copying `post-commit` into the `.git/hooks` directory. This can be done simply by running the install script (note that the `_4DSEE_ROOT` enviromental variable **must** be set.)

```bash
install.sh
```

## Manual Usage
The python script `formatHeader.py` assumes that an enviromental variable has been set which points to the root of the 4DSSE project. This is used to retreive the git log so that author information and last update date information may be read. By default this uses the enviromental variable `_4DSSE_ROOT`; however, this may be changed with the `--root` command line flag. Whatever is set as `--root` will be the name of the enviromental variable this script will search for.

General usage might look like
```bash
python formatHeader.py ../../src/meshIO/private/meshIO.cpp
```

This will automatically add the following (or similar...) header to the file

```
/* ***********************************************************************
//
//   Copyright (C) 2025 -- The 4D-STAR Collaboration
//   File Author: Emily Boudreaux
//   Last Modified: February 16, 2025
//
//   4DSSE is free software; you can use it and/or modify
//   it under the terms and restrictions the GNU General Library Public
//   License version 3 (GPLv3) as published by the Free Software Foundation.
//
//   4DSSE 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 Library General Public License for more details.
//
//   You should have received a copy of the GNU Library General Public License
//   along with this software; if not, write to the Free Software
//   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
//
// *********************************************************************** */
```

The project name may be changed with the `--project` command line argument. `--project` defaults to "4DSSE"

## Notes
- Generally this script is **not** meant to be directly invoked. Rather, it is meant to be run as a pre-commit-hook automatically. 
- There are defaults for root and project; however, they can be configured with command line options so if they change with time those changes can be easily propegated to this script.