Why Git

LibCL uses the git version control system to store all its libraries. Git was chosen for a few reasons.

• It is fast and efficient.
• SHA1 hashes and integrated PGP help fight corruption.
• The complete contents, not just diffs or individual files, are captured atomically.
• It supports distributed mirroring, development, and forking.
• It has good support for other VCSs.

How LibCL uses Git

Currently, LibCL has settled on the following repository layout.

• LibCL-git
  • Root URL of all LibCL git projects
  • LibCL-specific projects are hosted directly in this directory
• LibCL-git/upstream
  • pure mirrors of upstream projects
  • sufficient details to attach a git clone to the upstream project
• LibCL-git/local
  • selected branches from upstream
  • local patches to upstream libs
  • local release tags

All repositories are world-readable via http. Contributions should be made by git-format-patch or by cloning a repository and requesting a pull. Frequent contributors may be given write access via ssh.

To see both upstream and local versions in the same repository, clone from upstream and use git-remote to add the local repository.

How to use Git

If you are new to Git, here are some useful resources.

• Pro Git
• The thing about git
• Documentation links
• Git Tutorial
• Everyday Git
• Git User's Manual

Here are some of my recommendations.

• Always have gitk --all loaded for the repo you're working on.
• Update (not reload) gitk after modifying any branches or tags; this leaves the old objects displayed.
• Reload gitk to hide deleted branches you're comfortable with losing.
• git reset --hard $OLDSHA1 can clean many messes, letting you try again. USE WITH CAUTION!
• Use temporary tags as placeholders when merging branches or rewriting history.
• Learn by playing around with local clones of a read-only remote repository. Destructive testing is good way to learn git.
• Install some of the git contribs, especially git-completion.bash and git-new-workdir.
• Use git rebase to maintain (private) local patches on a master branch.
• Rarely use git pull. Much better to git fetch, check in gitk, and proceed as appropriate (e.g. with git rebase).