Giter VIP home page Giter VIP logo

git-rcs-keywords's Introduction

GIT-RCS-KEYWORDS

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.

Requirements

The project requires Python and git be installed and available from the system path. Both Python 2 and 3 have been tested successfully.

Supported keywords

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
$Id$ Composition of the file name, commit date, and author name
$Date$ Date the change was committed to the repository
$Author$ Author's name and e-mail address from the commit log
$Rev$ Date the change was commited
$Revision$ Date the change was commited
$File$ Name of the file
$Source$ Name of the file complete with relative path
$Hash$ 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

Installation

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.

Technical details

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:

  1. 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)

  2. 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

  3. post-merge event - re-process files found during the latest git merge action as the result of a git pull or git merge action

  4. 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.

License

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.

git-rcs-keywords's People

Contributors

mdrotthoff avatar

Stargazers

avatar avatar avatar avatar

Watchers

avatar avatar

git-rcs-keywords's Issues

Problems with installing and operating on Windows

Hi, I'm experiencing some problems in using your tool.
I found some fix/workaround but I'm still getting errors and I'm unsure if everything will work correctly.
My current configuration is
OS: Windows 10 Pro 64 bit
Git: 2.35.1.2
Python: 3.10.3

All tests are performed using git-bash
note: some error message is loosely translated from Italian to English, so it may not match perfectly with the actual English version message

###
Problem [1]

-> mkdir test-repo
-> cd test-repo
-> git init
-> ~/Downloads/git-rcs-keywords-master/install.py
fatal: no such section: filter.rcs-keywords
-> ~/Downloads/git-rcs-keywords-master/install.py

So, a second execution of install.py does not return errors.
It may be fixing some things during the second run, and/or it may be skipping the problematic steps because it found some files in the .git hierarchy, thus believing that installation has been previously completed.
The .git/filters directory is not there, anyway.

A third run gives back this:

-> ~/Downloads/git-rcs-keywords-master/install.py
Traceback (most recent call last):
  File "C:\Users\CI\Downloads\git-rcs-keywords-master\install.py", line 408, in <module>
    install()
  File "C:\Users\CI\Downloads\git-rcs-keywords-master\install.py", line 390, in install
    install_git_keywords(repo_dir='')
  File "C:\Users\CI\Downloads\git-rcs-keywords-master\install.py", line 327, in install_git_keywords
    register_file_pattern(git_dir)
  File "C:\Users\CI\Downloads\git-rcs-keywords-master\install.py", line 271, in register_file_pattern
    os.rename(attribute_file, attribute_backup)
FileExistsError: [WinError 183] Can't create a file, if it already exists: '.git\\info\\attributes' -> '.git\\info\\attributes~'

Impact: non working installation
Solution: run git-bash as administrator.
It still requires a double run of install.py (see above), but it seems to be working.
In some previous attempt it reported a failure in creating symlinks, running as administrator solved that, although I could not reproduce the scenario.

###
Problem [2]

-> git add test.txt
.git\hooks\rcs-filter-clean.py 'test.txt': .githooksrcs-filter-clean.py: command not found
error: external filter '.git\hooks\rcs-filter-clean.py %f' failed 127
error: external filter '.git\hooks\rcs-filter-clean.py %f' failed
warning: LF will be replaced by CRLF in test.txt.
The file will have its original line endings in your working directory

Impact: non working filtering
Solution: I edited .git/config replacing double backward slashes with single forward slashes

Before:
[filter "rcs-keywords"]
	clean = .git\\filters\\rcs-filter-clean.py %f
	smudge = .git\\filters\\rcs-filter-smudge.py %f
After:
[filter "rcs-keywords"]
	clean = .git/filters/rcs-filter-clean.py %f
	smudge = .git/filters/rcs-filter-smudge.py %f

###
Problem [3]

-> git commit -m "test msg" test.txt
".git" is not recognized as an internal or external command operable program or batch file.
[master (root-commit) b860aab] test msg
 1 file changed, 9 insertions(+)
 create mode 100644 test.txt

-> git checkout test.txt
Updated 0 paths from the index
""\".git" is not recognized as an internal or external command operable program or batch file.

-> rm -f test.txt
-> git checkout test.txt
Updated 1 paths from the index
""\".git" is not recognized as an internal or external command operable program or batch file.

Impact: unknown
Solution: unknown

###
Checking out test.txt does not change anything.
Removing test.txt and checking it out again successfully perform keywords expansion.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.