Help with Git

git is a free, open-source distributed version control system. One advantage of using git is that the latest version of the Atlas software is always available. This page covers the git commands most relevant to Atlas users.

Primary Commands

To download the software for the first time:

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

Once you have done git clone, most other commands operate locally from within the atlasofliegroups directory. To update your local copy with the latest changes:

git pull origin

Branches

There are several branches of the Atlas code. The main branch is master — most users never need any other branch. After cloning, you can check which branch you are on:

git branch

To see all remote branches:

git branch -r

The primary branches are master, unitary, and latest. To clone a specific branch, e.g. unitary:

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

To switch to another branch from your current one:

git checkout latest

To update only the master branch:

git pull origin master

Other Helpful Commands

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

git status

To show recent commit history:

git log
git log --oneline

The --oneline option gives more succinct output. To launch a graphical git browser (requires gitk):

gitk

Git help commands:

git          # short help
git --help   # longer help
git tag --help   # help on a specific command

Some commands have dry-run versions that show what would happen without doing it:

git pull origin --dry-run

Getting Unstuck

If you only ever pull code from a single branch, you should rarely run into trouble. But if you see a merge conflict like:

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

Try stashing your local changes first:

git stash
git pull origin master

Then restore your modified files:

git stash pop

If you are not making changes to the code and have a persistent problem, the simplest fallback is to delete your current directory (including the hidden .git subdirectory) and start fresh with a new git clone.

More on Git Objects

The main git object is a commit, which contains a tree (a snapshot of a directory) plus metadata. To browse commits:

git log --oneline    # shows list of commits

The output looks like:

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

You can refer to each commit by the first few characters of its hex name:

git show 94a5   # show details about a commit

See Git Objects for more detail.

Tagging and Branches

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

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

Example of creating a tag:

git log --oneline
b1c0fdd Updated version to 0.4.6 in version.h
...
git tag version_0_4_6 b1c0f
git push --tags    # push the tag to the server

Git References