Git User Guide

This is a reference guide on relevant git commands to use and maintain this repository. For more extended reference you may want to visit the following public tutorials:

• Git-SCM documentation
• Code School

Setup your github account:

Sign up in github -> Edit your profile -> SSH Keys -> Add SSH Key (Upload your public SSH key).

Create

You can create repositories in your own account, or in an organization that you are a member of. In this case we have created the ACS repository under ACS-Community organization.

Clone

To clone a repository:

mac - ~ $  git clone username@host:/path/to/repository

To clone the ACS repository:

mac - ~ $  git clone [email protected]:ACS-Community/ACS.git

This command will create a folder in your local file system with the ACS repository.

Add & Commit

You can propose changes (add it to the Index) using

mac - ~ $  git add <filename>

or

mac - ~ $  git add *

or

mac - ~ $  git add .

This is the first step in the basic git workflow. To actually commit these changes:

mac - ~ $  git commit -m "Commit message"

Now the file is committed to the HEAD, but not in the remote repository yet.

Push

To send those changes to your remote repository:

mac - ~ $  git push origin master

Change master to whatever branch you want to push your changes to.

Pull

To update your local repository to the newest commit:

mac - ~ $  git pull

Tags & Releases - git

It's recommended to create tags for software releases. For example this line will show you the existing tags in your repository:

mac - ~ $  git tag

To create a new tag:

mac - ~ $  git tag -a v0.1 -m 'Initial version'

Switch the local copy to a specific tag:

mac - ~ $  git checkout tags/<tag_name>

Tags & Releases in Github

Github provides a easy way to create tags & releases: after commit & push the changes, you can create new tags & releases using the web interface: Creating Releases.

Submodules

Git has something called submodule support. This allows you to specify one or more other git repositories within another (like svn:externals):

mac - ~ $  git submodule add [email protected]:other_project.git 
mac - ~ $  git commit .gitmodules other_project -m "Added other_project submodule" 
mac - ~ $  git push 

Cloning a tree with submodules

Git doesn’t automatically fetch all your submodules, to add to your local directory:

mac - ~ $  git submodule init [email protected]:jantogni/testing.git
mac - ~ $  git submodule init
mac - ~ $  git submodule update

To git clone including submodules directly:

mac - ~ $  git clone --recursive [email protected]:jantogni/testing.git

Pull latest of all submodules

To pull the latest version of each submodules:

mac - ~ $  git submodule foreach git pull origin master
mac - ~ $  git commit -am "Pulled down update to ..."

Git and SVN

Git and SVN repository can interact using git svn. This utility contains several commands allowing bidirectional operation between Subversion and Git.

The tutorial to setup a git repository from another SVN repository is here

In summary, the following is the workflow used in a git svn repository:

1. Clone the svn repository using git svn clone <svn_respository_address>
2. Work locally on the changes you want to do
3. Synchronize back changes from the remote svn repository using git svn rebase. There may be conflicts, resolve them according to git guidelines
4. Push the changes done locally to the remote svn repository using git svn dcommit. This command change your commit data, adding extra info to the commit message changing the SHA1 checksum of the commit.