Help with git

git is a distributed version control system. It helps developers handle their projects. Git is easy to learn. It is also free and open source. One advantage of using git is that the latest version of the software is always there

This page is organized into the following sections:

Primary commands

To download the software, do:

git clone https://github.com/jeffreyadams/atlasofliegroups.git

Once you have done git clone, most other commands operate locally. Everything is done from within the atlasofliegroups directory, using meta-information in the .git subdirectory.

To update the software, do:

git pull origin

will update your local copy of the software with the latest changes.

Branches

There are several branches (versions) of the atlas code. The main branch is named master. Most users never need any other branch. After you have done git clone you can cd into the newly downloaded directory and do:

git branch

This will show you which branch you are on (the default is master). To generate a list of all remote branches, do:

git branch -r

The primary branches are master, unitary, and latest. The master branch is probably what most users would want. If you choose to download a specific branch, say the branch with name “unitary”, you can do:

git clone -b unitary --single-branch https://github.com/jeffreyadams/atlasofliegroups.git

To switch into other branches from the current branch, do:

git checkout latest

This will switch you into the branch named “latest”.

To update only the master branch do:

git pull origin master

This will also update the atlas software.

Other helpful commands

Again, after you have done git clone, most of these commands operate locally. Use you terminal to navigate into the “atlasofliegroups” directory.

To show the status of your local repository, compared to the remote one, do:

git status

To show a lot of information about the repository, including recent activities, do:

git log
git log --oneline

The --oneline option gives you a more succinct output.

To launch a graphical git browser, do:

gitk

However, you need to have gitk installed.

Many commands of git have help options:

git # This gives short git help.
git --help # This gives longer git help.
git tag --help # This gives help on tagging.

Some commands have dry-run versions:

git pull origin --dry-run

says what the command will do, but doesn’t do anything.

Getting unstuck

If all you ever do is pull code, from a single branch, hopefully you won’t run in to trouble. Suppose this happens:

git pull origin master
file test.rx not up to date, cannot merge

and the update from google will not execute (at all). Do this:

git stash
git pull origin master

to stash your local changes, and execute the update from google. Then do:

git stash pop

to bring back your modified files. There are other variants of git stash, see the references.

If you are not making changes to the code, but have a problem, it is always easy to start from scratch. Delete your current directory (don’t forget to delete the invisible .git directory), or start a new directory, and start over with a fresh git clone.

More on git objects

This is a quick overview. See The Git Objects for more detail. The main git object is a commit.

A commit contains a tree, which is a snapshot of a directory, together with some meta-information. Here are some commands for working with git objects:

git log
git log --oneline    # This shows list of commits

The output is something like:

4826100 ...
94a5663 ...
268f5d4 ...

You can refer to each commit by the first few letters of the hex name. For example:

git show 94a5   # This will show you details about the second commit

Tagging and branches

Tags are (mainly) a way to give user-friendly names to commits:

git tag    # Print list of tags
git tag -n    # Print list of tags with more information

Here is how I created the version_0_4_6 tag:

git log --oneline
b1c0fdd Updated version to 0.4.6 in version.h
bbca5d3 deleted README-git
bb64257 edited README-git
...
git tag version_0_4_6 b1c0f
git push --tags    # To make the changes on the server

Git references

The O’Reilly book Version Control with Git, by John Loeliger is quite useful.

There is a lot of browsing you can do at the Atlas page at github, including looking at different branches and tags.