This page describes conventions and best practices applicable to the Fedora Git repository.
| Table of Contents |
|---|
Overview of the Git Lifecycle
Git essentially allows a developer to create a local subversion repository on their workstation, do all their work and commits in that local repository, then push the state of that repository back to a central facility (github).
Bearing in mind that you will always being doing your work and commits locally, a typical session looks like this:
git clone git@github.com:fcrepo/fcrepo.git && cd fcrepo
Get a copy of the central storage facility (the repository).
git branch fcrepo-756
Create a local branch called "fcrepo-756".
git checkout fcrepo-756
Create a local copy of the branch if it doesn't exist, make it your active working branch.
Now, start creating, editing files, testing. When you're ready to commit your changes:
git add file
This tells git that the file(s) will be marked as managed by git. You'll need to do this on files you just modify, also.
git commit file
Commit your changes locally.
Now, the magic:
git push origin fcrepo-756
This command pushes the current state of your local repository, including all commits, up to github. Your work becomes part of the history of the fcrepo-756 branch on github.
git push is the command that changes the state of the remote code branch. Nothing you do locally will have any affect outside your workstation until you push your changes.
{git pull}} is the command that brings your current local branch up-to-date with the state of the remote branch on github. Use this command when you want to make sure your local branch is all caught up with changes push'ed to the remote branch.
Some useful terms
master: this is the main code branch, equivalent to trunk in Subversion. Branches are generally created off of master.
unpublished vs. published branches: an unpublished branch is a branch that only exists on your local workstation, in your local repository. Nobody but you know that branch exists. A published branch is one that has been push'ed up to github, and is avaialble for other developers to checkout and work on.
fast-forward: the process of bringing a branch up-to-date with another branch, by fast-forwarding the commits in one branch onto the other.
rebase: the process by which you cut off the changes made in your local branch, and graft them onto the end of another branch.
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!
...
In this graph, Harry's local commits and pull merges appear to have occured occurred in master. Tom's commits (which were always pushed immediately to master) appear to have occured occurred in a separate branch. In a way, this is actually an accurate representation of what has occurred. Harry made some commits in his master branch, merged in changes from a another branch three times, then replaced the repository master with his own.
...
Let us use the same Tom, Dick, & Harry example, except with Harry performing his development in a local, non-published branch. In this example, harryHarry's workflow looks like the following:
...
Development in an unpublished local branch, and using git rebase instead of pull or merge to update the local branch with changes to master is also a valid pattern. This technique results in the elimination of the local branching history, and rather than a final merge applies all local commits in sequence to the end of the current master. This may be used when the local branch and merge history is unimportant or unneecessary unnecessary (perhaps bad luck - while making two trivial local commits, somebody happened to push master in the meantime).
...