Source control programs manage changes to a software project and allow multiple programmers to work together without destroying each other's work. Even for a single programmer, source control will allow you to create branches of the same project for different clients, or to rollback changes to an older version of the project. The most popular source control programs for Linux are Subversion and Git. This page discusses how to get started with Git.

Many Linux IDE's have built-in support for Git and subversion but they usually expect you to be familiar with source control concepts.

 Git Concepts

Git stores the project in a directory called the repository. This is a kind of database that records all the files and changes in the project. Unlike some other source control software, the repository attached to your project and is not located in another place.

There are three basic Git activities:

• Clone - get a copy of a project
• Pull - update your repository with with any changes made by other developers
• Commit - submit your changes.
• Push - submit your committed changes to the other developers (or let them pull from you). The project must be updated and changes committed before it can pushed.

 Major differences compared to Svn

Git is a revision control system loosely based on the commercial "BitKeeper" program. It can interact with Subversion but it uses a different strategy. Some differences between Git and Subversion (or CVS) are:

• Git has no central, remote repository. Your working area also as your repository attached to it. You can make as many other repositories as you want.
• Git uses a two-stage commit. Rather than saving all changed files, you select (or "stage") the files you want to commit. These are added to a commit list. When you commit, the files in the list are committed.
• Git creates branches easily. Branches do not require special directories. Branches are a convenient way of separating different tasks and one user can grab a branch from another to continue work on a particular problem.

 Setting up Git

For a new user, you should start by configuring your name and email address. Git will use these when identifying you in the change history.

$ git config --global user.name "First_Name Last_Name"
$ git config --global user.email "you@yourcompany.com"

Git does not require a central, report repo to be shared. To create a new project, create a new directory and use git init.

$ mkdir myproject
$ cd myproject
$ git init

If you are working on a team and want to created a shared repo to merge changes, you can create a "bare" repository (one with no working area because it's not for a user). Make sure it is shared.

  $ mkdir ourproject
  $ cd ourproject
  $ git --bare init --shared

To get a copy of the an existing project, you "clone" (or copy) the project. If we want to use the "ourproject" project, you would use:

  $ git clone URL_to_project/ourproject

Git uses URL's to refer to the respository and the projects stored inside of it. If the other respository is /home/repository/git/svnroot:

• /home/repository/git/svnroot - the repository on the local machine. (Or use file: in front)
• git://other/home/repository/git/svnroot - the repository is on the machine called "other" and is accessed through a git daemon
• ftp://other/home/repository/git/svnroot - the repository is on the machine called "other" and is accessed through FTP
• rsync://other/home/repository/git/svnroot - the repository is on the machine called
• http://other/home/repository/git/svnroot - the repository is on the machine called "other" and is accessed through Apache WebDAV
• rsync://other/home/repository/git/svnroot - the repository is on the machine called "other" and is accessed using rsync
• ssh://other/home/repository/git/svnroot - the repository is on the machine called "other" and is accessed through Secure Shell (SSH)

There are some other protocols as well.

 Working on a Git Controlled Project

Git uses a "two stage commit". Instead of automatically committing all files, you must choose which files you want to commmit. The status command shows the current status of your files. "Untracked" means that these files are being ignored by Git. "changed but not updated" means these files have been changed and those changes haven't been committed yet.

Use the add command to stage a new (or changed) file for commitment to the repository. (Use the rm command to delete a file.) These files will appear in your status as "changes to be committed". Use commit to commit your changes.

  $ git add ChangeLog
  $ git commit -m "updated the change log"

 Sharing work on a Git Controlled Project

To update your project with the latest changes by your fellow programmers, type:

  $ git pull

You can also update individual files (instead of the directory) by naming files in the command.

To commit your changes to the project so they can be seen by your fellow programmers, type:

  $ git pull your_repository_url

or

  $ git push another_repository_url

Push is usually preferred to pull because git can perform better merging on your computer.

When you push files, the other user cannot be using the same branch or the push will fail. For example, pushing your master branch to the other programmer's master branch will fail if the other programmer has his master branch checked out. The other programmer will need to switch branches first.

You can also commit individual files (instead of the whole directory) by naming files in the command. To avoid typing in descriptions, you can include a description of the changes using -m "message" where message is the description to put in the change log.

To resolve conflicts, fix the file with the conflict, add it and continue with get merge --continue.

 Using Git Remotely

To use Git remotely, the most common method is over a Secure Shell connection (SSH). Create a secure shell connection and setup your SSH authentication keys so you won't have to type a password. If you've never used SSH, you'll need to generate a pair of SSH keys (e.g. ssh-keygen -t rsa), copy the public key (.ssh/id_rsa.pub) to the remote home directory (or add it) (.ssh/authorized_keys) and make sure the remote key file is not world readable (otherwise it is an automatic rejection by SSH).

  git clone ssh://armitage/home/repository/svn/svnroot/test_project

If you have to go through a firewall, make sure that the secure shell (port 22) is allowed through to the computer with the repository.

 Using Git Remotely on a Different Port

Sometimes you may want Git to work through a different network port than the SSH default. For example, you might be port forwarded through a firewall to a particular machine. Alternatively, port 22 might be used to SSH to a firewall and another port will need to be used to SSH to an internal machine. Git handles this by adding a colon and a port number in your repository URL.

 Using Git to Rollout Projects

You can sometimes use Git to rollout projects, especially web sites. On the production machine, move to the root web directory and use Git to update the web site (or check out the web site if this is the first time). This will create Git .git directories (as if the web site was a developer) but it will also update the files on the entire web site. Check file ownerships and permissions as needed.

 Git Terms

What is "fast forward"? The changes can be applied without merging your work with the work of another team member. Fast forwards can never have a merge conflict.

A "non-fast forward errors" usually means Git can merge the work but, to do so, it will break the commit history in the log. In a team environment, it means that your log will no longer match other team member's logs, so git will refuse to perform the update. Using --force in this circumstance will make the merge the changes anyway. There are workarounds.

What is the "index"? The list of files staged to be committed. Hence, working with the index means changing which files are tracked or are going to be comitted.

What is "rebasing"? Reorganizing your log (your commit history), in the sense of pulling in changes from your teammates and reapplying your changes on top of the latest commits...these new commits form a new "base" on which to place your work.

 Common Git Tasks

• Clone w/out history: git clone -r HEAD url # copies latest version, discards history
• Revert a file: git revert HEAD file # reverts one revision
• Undo an add/rm: git reset HEAD -- file # restores file
• Untrack a file: git rm --cache file # removes file from git, leaves it in your directory
• Updating with uncommitted changes present: git stash, git pull, then git stash pop # saves uncomitted files, updates, then restores uncommitted files
• Restore a deleted file when you don't know when it was deleted: git log file #note the commit codes, git checkout commitcode -- file
• Squash commits before sharing work: git rebase --interactive HEAD~n
• Convert a regular repo into a SSH shared repo: git repo-config core.sharedRepository true, git branch unlocked, git checkout unlocked
• Create a shared repo (no working area): git --bare init --shared
• Change to github repo: git remote rm origin ; git remote add origin URL ; git push -u origin master
• Resolving a git stash conflict: git add ; git commit ; git stash drop

This is a basic tutorial. Read the Git documentation for more features.