This project provides a means to add keyword expansion of standard RCS tags to your git projects. The mechanism used is a combination of git filters and git event hooks. Keywords are handled in a non-case sensitive fashion for expansion purposes.
The project requires Python and git be installed and available from the system path. Both Python 2 and 3 have been tested successfully.
The following list represents the keywords that will be substituted each time a relevant file is checked out of the git repository. It also specifies what value will be used in the expansion. Note: git does not have a way of directly supporting a revision number so the commit date is substituted to provide a means to determine the currency / ordering of the source file versions. The expansion will only be performed to the local copies. The file version actually stored in the repository will NOT be in expanded form.
| Keyword | Value used |
|---|---|
| Composition of the file name, commit date, and author name | |
| Date the change was committed to the repository | |
| Author's name and e-mail address from the commit log | |
| Date the change was commited | |
| Date the change was commited | |
| Name of the file | |
| Name of the file complete with relative path | |
| Commit hash of the change |
By default, the following file name patterns are registered by the installer as supporting RCS keyword expansion. Additional file name patterns can be manually added to the file .git/info/attributes is so desired.
- *.sql
- *.ora
- *.txt
- *.md
- *.yml
- *.yaml
- *.hosts
- *.xml
- *.jsn
- *.json
- *.pl
- *.py
- *.sh
To install the RCS keyword expansion support, execute the install.py program in the
repository. This may either be done by executing the installer from the root of the
git repository or by providing the directory path of the repository root on the
command line. The installer will copy the two filter programs into the .git/filters
folder of the repository. Additionally, the four event hook programs will be copied
into the relevant event subfolder (named <event>.d) in the .git/hooks folder.
A git hook manager will be also be copied into the .git/hooks folder to act as a
control program to allow multiple event hooks to exist for each event being
registered. Next, the installer will register the filters in the .git/config file
so that they will be called as needed by git. The installer will also register the
(hard-coded) file patterns into the file .git/info/attributes to control which files
in the repository are managed by the filters. Finally, if the repository has any
sub-modules, the filters will also be installed into the submodules.
There are two filters programs registered with the git repository. The clean filter is registered to convert the RCS keyword from an expanded state to a keyword state. This allows the keyword without expansion to be stored in the git repository. The clean filter is run whenever a file is added to the git change log prior to committing the change to the local git repository. It is also executed when git compares the local source to the repository version. The smudge filter is registered to convert the RCS keywords into an expanded state for storage in the local copy of the repository. The smudge filter is run whenever a file is checked out as the result of a commit, branch change, or any other time the file is created from the git repository.
Additionally, there are four git event hooks registered to ensure that the data used in expanding the RCS keywords is accurate and consistent. Due to the method git uses to manage pulling changes from the remote copy of the repository, the events are used to trigger a fresh checkout of the modified files under specific conditions. Note: The event hooks exclude from this process any file that has been modified by the user. So if a file has been modified since a git add but before the git commit action, it will NOT be replaced (and the keywords not expanded). The four event hooks registered are:
-
post-checkout event - re-processes files found during a git checkout that may not have had up-to-date commit information at the time of the checkout (such as during a git pull action)
-
post-commit event - re-processes files which were just added to the local repository as a part of a git commit action so that the keyword data is re-expanded for the latest commit
-
post-merge event - re-process files found during the latest git merge action as the result of a git pull or git merge action
-
post-rewrite event - re-checkout files found to have been rewritten during a git rebase operation.
Finally, a program is installed into the git hooks directory which controls access to
the various git event hooks. This allows each git event to have multiple hooks for a
specific event. This is done by creating a subdirectory named <git event>.d for each
of the registered git events to hold the associated hook programs. A symbolic link is
created from the control program to the git event being managed. Note: The hooks
are executed in a sorted fashion so there is some control over the order the hook
programs are executed.
This project is provided as-is without any warranty of fitness. The concepts and ideas used came from various other similar projects as well as original research. To the extent possible, this project is released to the public domain.