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
To get started, you need to clone the repository.
git clone ssh://email@example.com/cvs/projects/jdemsoc
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
Finding out what is your active branch¶
To find out what is your active branch, use:
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:
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
- Commit all the changes in your working tree to your development branch
- Set your working branch to be
- 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:
- leave it be, because it doesn't take much room in your repository and you may later decide it was good after all, or
- 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:
To upload your changes to the central repository, use:
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).
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