The following helpful git tips, as so many others, are attributed to Ian Schneider and have been stolen from his email.
The GeoTools git repository holds the source code for GeoTools:
This repository is setup with the following branches of GeoTools:
this is what we are currently working on
stable development branch
Typical Development Environment¶
Typically, a developer will create a local
geotools directory, move into
that directory, and do a checkout of the GeoTools repository. Within the
repository switching between branches is trivial:
[geotools]% git branch 2.7.x 8.x * main [geotools]% git checkout main [geotools]% git checkout 8.x [geotools]% git checkout 2.7.x
Developers generally do most work on a branch, even small scale bug fixes. This is typical with Git since branches are so cheap:
[geotools]% git checkout -b bugfix main [geotools]% git branch 2.7.x 8.x * bugfix main
A developers repository will usually contain several of these “feature branches” but they generally never get pushed into the main/canonical git repository.
Git is unlike version control systems such as Subversion and CVS in that commits are always local. It is not until one pushes local commits up to a repository that they become “public”. The basic workflow of a single change in git is:
Make a change
Stage the change
Commit the change
Push the change
While extra steps may seem cumbersome at first they are actually very handy in many cases. For example consider making a
git status gives the current state of the local repository:
[geotools]% git status # On branch main # Changes not staged for commit: # (use "git add <file>..." to update what will be committed) # (use "git checkout -- <file>..." to discard changes in working directory) # # modified: advanced/build/source.rst # no changes added to commit (use "git add" and/or "git commit -a")
Which reports that we have modified a single file but have yet to stage the file for commit. We use
git add to
stage the file for commit:
[geotools]% git add advanced/build/source.rst [geotools]% git status # On branch main # Changes to be committed: # (use "git reset HEAD <file>..." to unstage) # # modified: advanced/build/source.rst #
Status now reports the file is ready for commit. The syntax of
git commit is identical to that of Subversion:
[geotools]% git commit -m "updating documentation for change to git"
Doing another status reports no more local changes:
[geotools]% git status # On branch main # Your branch is ahead of 'geotools/main' by 1 commit. # nothing to commit (working directory clean)
But also reports that our local branch is ahead of the remote branch by 1 commit. This is because we have yet to push the commit. Before pushing it is always a good idea to first pull in case we have any commits that conflict with other commits that have already been pushed up to the repository:
[geotools]% git pull geotools main [geotools]% git push geotools main
At this point the change has been pushed up to the remote git repository.
Git uses a special file named
.gitignore that contains a list of files and patterns to ignore:
.project .classpath .settings target *.patch *.class
These settings ignore files not suitable to be committed into the repository such as eclipse project files, compiled class files, and patch files.
.gitignore file is located in the root of the repository but such a file can be
contained in any project directory.
How to rollback a change depends on which stage of the workflow the change is at. For changes that have yet to be staged it is
simply a matter of using
git checkout /path/to/file/to/rollback
If the change has been staged but not yet committed:
git reset HEAD /path/to/file/to/rollback git checkout /path/to/file/to/rollback
If the change has been committed but not pushed it gets interesting. If the change to rollback is at the tip of the branch (i.e. is the most recent commit) you can use git reset:
git reset <previous_commit>
previous_commit is the commit that is directly before the commit to rollback.
If the change has been committed but not pushed and the change is not at the tip of the branch then an interactive rebase can be used:
git rebase -i <previous_commit>
previous_commit is the commit that is directly before the commit to rollback. An interactive rebase provides
an editor that allows us to delete commits from history. With it we can simply delete the commit(s) we wish to revert
and it will be as if it never happened. Again it is important to note that this can only be done on local commits that
have yet to pushed up to a remote repository.
If the change has been committed and pushed up to a remote repository then the only option is to manually roll it back by
applying a revert commit. Thankfully git provides the
git revert command for just this purposes:
git revert <commit>
commit is the commit we wish to roll back.
Tells you info about commits/revision history:
My favorite. Annotates a document with who changed what and when:
git blame Sample.java