Marc's suggested git workflow

This is (the start of) a simple git workflow that I have found reasonable to use. I am not extremely experienced in the use of git, so please ignore these instructions (or, better yet, improve them) if you know better.


working tree: the set of files and directories in your filesystem which are under management with git
clean: a working tree is clean if it matches the HEAD of your repository

Getting started

To get started, you need to clone the repository.

git clone ssh://

This will create a directory named jdemsoc under your current working directory; this directory will contain a copy of the jdemsoc repository. This gives you a complete local copy of the repository. You can make whatever changes you want to your repository without having any effect on the central repository you just cloned.

Making local changes

In order to make it easy to work incrementally on changes to jdemsoc, I find it useful to do essentially all my development on a branch. By doing the same, you can make speculative changes of whatever scale you want, and decide when you are done whether to keep those changes (by merging the changes back onto your master branch), or to abandon those changes (by not doing anything). It is easy to keep several branches under development at the same time, if you are working on unrelated items in the same repository (e.g. changes to two different documents). Any branches you make are visible only locally, to you, not to others sharing use of the central jdemsoc repository.

Finding out what is your active branch

To find out what is your active branch, use:

git branch

This lists all the branches in your repository, and indicates the current branch with an asterisk.

Creating a branch

To create a new branch, and simultaneously make it your currently active branch, use:

git checkout -b name-of-my-new-branch

where name-of-my-new-branch should be replace by the name you want your new branch to have.

This both creates the branch (in your repository) and makes it be your currently active branch. This command does not modify your working tree. You should use this command only if your working tree is clean.

Checking to see if your working tree is clean

To find out if your working tree is clean, use:

git status

This will tell you of any files you have modified, or any files you've added without committing.

Changing your current branch

You can change freely between branches, if you've committed all your changes to your current branch. The command to change your current branch, to an already existing branch, is:

git checkout name-of-already-existing-branch

This command will file, with an error message, if you have changes to your working tree that have not been committed. So, before switching to a different branch, make sure to commit all your changes. If you want to abandon the changes, you can use git checkout name-of-file-to-restore to restore the repository version of a file you have modified. If you have many files to restore, you might use git reset --hard. Be careful, because you can't recover your changes if you lose changes if files you didn't mean to lose.

Saving the results you like

When you have a set of changes you want to keep as your main line of development, you need to merge the branch containing those changes back into the master branch.

  1. Commit all the changes in your working tree to your development branch
  2. Set your working branch to be master
  3. Then merge the development branch into the master, with:
git merge name-of-development-branch

Once you have merged your changes back into your master branch, you can delete the development branch without losing any work:

git branch -d name-of-develoment-branch

Forgetting about changes you don't like

If you decide your development branch was junk, and want to get rid of it, do not merge it back into master. Instead, you can either:

  1. leave it be, because it doesn't take much room in your repository and you may later decide it was good after all, or
  2. throw the branch away, with
    git branch -D name-of-development-branch

    Note the capital letter D: this will delete a branch that contains work not otherwise saved, so be careful with it.

Sending your changes back to the central repository

After you have merged your changes onto your local master branch, you may want to send those changes back to the central repository. First, you should always make sure to download any changes from the central repository to your repository. Second, you can upload your changes.

To download changes from the central repository to your repository, use:

git pull

To upload your changes to the central repository, use:

git push

Comparing your working tree to the remote (central) repository

To compare your working tree to the remote (central) repository from which it was cloned, one first fetches the changes from the remote repository into your local clone -- but without merging those changes into the master branch of your own repository. To do this, use git fetch (not git pull, which was used above).

git fetch

Now the branch your local repository has as origin/master matches what is in the master branch of the shared remote repository.
To compare your working tree to this branch, use the "triple dot" syntax of git diff:
git diff origin/master ... master

If your version of git is too old to have this shorthand, then you can do it "by hand":
git merge-base origin/master master
# some long SHA1 is returned
git diff the-SHA1-from-above

Either of these command sets (the triple-dot diff or the two-step merge-base + diff incantation) shows the changes that have been introduced to the remote (shared) repository since you last merged with it. After you have convinced yourself that you want to merge the changes from the remote repository into your master branch, you should use git merge to do so:
git merge origin/master