This page describes conventions and best practices applicable to the Fedora Git repository.
Line endings
All text files in must be normalized so that lines terminate in the unix style (LF). In the past, we have had a mixture of termination styles. Shortly after the migration to Git the master and maintenance branches were normalized to LF. Please do not commit files that terminate in CRLF!
Configuring git to enforce LF normalization
There are several way to enforce LF normalization. Each method carries some consequences, and the consequences & methods differ between versions of Git.
autocrlf property
Normalization rules for all text files can be addressed by the 'autocrlf' configuration property. There are two useful values for this property, depending on your platform
- autocrlf = input. Use on unix-like platforms. This will perform no conversion upon checkout, but will normalize any crlf files upon commit.
- autocrlf = true. Useful on Windows platforms. This will have the effect of converting all text files into dos-style (CRLF) in the working copy upon checkout. Upon commit, all files will be normalized to LF on their way into the repository, but remain in CRLF in the local working copy directory.
This property can be set globally for all local git repositories, or locally for a single git repository.
The autocrlf property can be set globally via the command line. For example:
git config --global core.autocrlf input
Executing this command is identical to editing your ~/.gitconfig file and adding:
The autocrlf property can also be set locally for a given git repository, such as the local clone of the fcrepo. For example, from within the local working directory:
git config core.autocrlf input
Executing this command is identical to editing the .git/config file within the git working directory and adding:
.gitattributes file
The presence of a committed .gitattributes file within the code can also be used to apply line-ending rules. This has the benefit of being part of the managed sources (and this part of a given branch, tag, etc), but is not understood by all versions of git. The fedora master branch has a .gitattributes file containing * text=auto, which instructs git to detect text files, and normalize to LF at each commit.
Git 1.7.1 and earlier
Earlier versions of git do not understand the necessary directives in .gitattributes file, so autocrlf is the only way to assure compliance with the LF normanlization. Thus
- Unix and mac users should set
autocrlf = input either globally or locally
- Windows users should set
autocrlf = auto either globally or locally.
These versions of git may apply/detect autocrlf settings to all files in the working copy immediately. Thus, if checking out older branches/tags/commits that still have crlf files in the repository, these files will be seen as automatically 'modified' when doing a 'git status'. This may have confusing side-effects. When working with older branches containing a mixture of line endings, you may want to either turn autocrlf off, or just go ahead and convert all files in the branch to LF.
Git 1.7.2+
These versions of git heed the .gitattributes directive, so it is not strictly necessary to set autocrlf, but it is recommended.
These versions of git will apply the autocrlf setting to new files - preventing the introduction of non-normalized crlf files into the repository, but ignoring existing crlf files.
Working with older branches
Text files were normalized to use LF in commit 5275b... Any existing branches/tags that are not normalized may contain a mix of files. Merging changes from a crlf file into a normalized branch may be problematic. In particular, merging any modified crlf file into its normalized counterpart will produce a conflict with a whole-file diff (i.e. it will appear as the entire file is in conflict). Converting any such files to use LF endings in the originating (old) branch is a reasonable solution, and will result in merges that behave as expected.
Commit Messages
Commit messages should follow the guidelines described in detail at http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html.
In summary:
- First line: JIRA issue ID in all caps (if applicable), followed by a brief description (~ 50 characters)
- Blank line
- Third line: more detailed description, line-wrapped at 72 characters. Link to JIRA issue, if applicable.
Use the present tense when writing messages, i.e. "Fix bug, apply patch", not "Fixed bug, applied patch."
Two sample commit messages
- linked to a JIRA issue:
FCREPO-780: NPE thrown on disseminations
Fix for the following bug: Fedora throws a null pointer exception if
you call a disseminator that fronts a web service whose response does
not contain a "Content-type" header.
https://jira.duraspace.org/browse/FCREPO-780
- general issue:
Create .gitattributes file to normalize line feeds
Create .gitattributes file requesting all text files normalised to LF.
Will be ignored by git versions < 1.7.2
See https://wiki.duraspace.org/display/FCREPO/Git+Guidelines+and+Best+Practices
for more information.