Git Workflow Introduction

Intro

So, Git is cool and powerful, but with all that cool stuff, we can sometimes get lost in what we can do, and not always do what is actually understandable when we look back on it after a mistake. Here I will try to give a quick introduction to using git, and put down some tips-and-tricks that I have learned thus far as a working stiff. =P

Some of this might overlap with what is on the project standards page, but hearing it twice will probably only just serve to rub it in a little more. :)

Using Git - Cloning a Repository

So, after you install git, you're probably going to start working with a repository from somewhere else (a remote repository). Now, git can act simply as a local version control system (a local repository), but we're going to be dealing with a remote repository setup here. However, when working on local topic branches (i.e. not pushed to remote/origin), you're essentially working with a local repository on your machine, that will later be pushed to the remote repository.

So, lets clone the repo here to your local machine (of course, assuming you have installed git and everything):

1	git clone git://git.code.sf.net/p/unitycf/code /path/to/your/repo/folder/

... and the repository will be pulled into the directory that you provided it. For developers hoping to actually be able to commit anything, make sure you use the RW (read+write) path, and not the read-only path, of the git repository. The path in the example above is the read-only path. The RW path has ssh:// instead of 'git://'. Of course, if you pull the read-only path, we can make your local repository read-write by changing a line in the internal config file, but that a story for another day. =]

If no directory is provided, a default one is created in your current working directory named the same as the git repo you're pulling from. Might as well make your target directory a clean one, as I don't really know what will happen if you try to clone a remote git repo into an already git init'ed directory... I wouldn't recommend it.

Topic Branches

When working on a git controlled project, just adding commits to the master branch is almost never done. Instead, a "topic branch" approach is often used. This makes commits and additions to the master branch clean and easy to track (especially when using the "gitk" tool, which has a graphical representation of the repository's branches).

So, now that we're thrown the fancy terminology at you, lets get to what it actually means. So, for the sake of this example, say we're working on a git branch that has no other branches than the master as of yet, like just after an initial commit, and we want to start work on a the first new feature of the project. If we called git branch, we would see:

1 2	$ git branch * master

showing that we don't have any other local branches other than master. If we called git branch -a, the "-a" option also shows the remote branches in the remote repository (aka. on SourceForge):

1 2 3 4

$ git branch -a * master remotes/origin/HEAD -> origin/master remotes/origin/master

Everything here that is prefixed with remotes/origin/ are branches on the remote repository. Don't worry about the HEAD branch, but one trick that I (Paul) use when pushing work on a topic branch to its remote counter-part is to call git push origin HEAD. While I don't know exactly what this does behind the scenes, what I know it does is:

• If your local branch doesn't have a remote counter-part:
  • Creates the remote branch with the same name as your local branch and sets it's HEAD to the current HEAD of your local branch.
• If your local branch does have a remote counter-part:
  • Pushed your local commits to the remote branch that is named the same as your current local branch

Merging

Ok, so we know how to create and manage topic branches. Eventually, after everyone gets working on their respective components on different branches, we want to obviously combine the code into a single branch to bring it all together. This is where git merge comes in. As it sounds, this command will merge a target into the current branch where this command is called from. This merger will happen on your local machine, so you don't have to worry too much about screwing the whole project up (you can always easily reset your local version to the version on the remote). However, when merging, we would like to enforce a standard of using the git merge --no-ff --log options (covered again on the [Project Standards] page). Using this prevents the commit from becoming "fast-forwarded" and adds a nice log message when it is merged into your current branch (which allows us to easily track things down later if needed).

There is a process of reverting merges, but its going to require a little bit or reading that I haven't done yet (see file:///usr/share/doc/git-1.7.1/howto/revert-a-faulty-merge.txt in internal documentation).

Working with a remote branch

If you want to work with a branch that has been labelled remote, you can't just checkout the branch. I order to actually track changes to the remote branch, and get the files associated with it, you'll have to set an option in your git config file. The following command does it for you:

1	$git config branch.autosetupmerge true

(tells git-branch and git-checkout to setup new branches so that git-pull(1)
will appropriately merge from that remote branch. Recommended. Without this,
you will have to add —track to your branch command or manually merge remote
tracking branches with “fetch” and then “merge”.)

Now you can checkout the remote branch and use it. Hurray.

Adding files to git

TODO: how to add, what files to add, files to not add

roughly:

git add <new file="">

git commit -m "this is a note about the commit"

git checkout -- ./Library

git push