Hints for Using Git

Git is a popular distributed version control system. It runs on Windows, Mac, and Linux
systems. It has command-line as well as graphical user interface. In this page, we provide
basic concepts and introduce basic commands of Git.

Install Git

Git can be downloaded free of charge from git-scm.com. For Linux and Mac, it is more
convenient to use the package manager to install git. For example, on Fedora linux, run
yum install git

will install git into the system. If the gui is needed, also include packages git-gui and gitk.

Start Using Git

Git keeps snapshots of project files instead of only the changes to the files. The versions are
stored in local directory named .git within the project directory, and can also be stored on
remote servers. The following steps show how to start using local Git on a Linux system.

Create a project directory:

mkdir projdir

Go to the project directory:

cd projdir

Initialize the git directory:

git init

Create files of the project: adding, removing, updating files.

Track all files in the project directory:
git add .

Commit tracked files to Git storage:

git commit -m "Initial Commit"

Check status of the project:

git status

Git maintains a staging area to track files that are changed. Before a file can be tracked, they
have to be added to the staging area. Staged (or tracked) files can then be committed to the
storage. Status of the files in the project is checked by git-status command.

Alternatively, we can also start a project from a version stored on a remote server (In Git
terminalogy, clone a repository, or repo). On a Linux system, this can be achieved by the
following steps.

Go to the parent directory of the project directory:

 cd $HOME

Clone a remote repo:

git clone git://github.com/UTSA-CS-3443/proj.git

Go to the project directory:

cd proj

Work with files of the project: adding, removing, updating files.

Track all files in the project directory:
git add .

Commit tracked files to Git storage:

git commit -m "Commit message"

This will create a local copy of the project and set up Git to track any changes made locally.
The remote repo will not be updated until a new version is pushed back to the server.

Normal Work Flow

Git takes a snapshot of the project at each commit point. The history of a project consists of a
set of snapshots, each is pointed by a commit object. Each commit object has a unique SHA-
1 hash value as it ID, and keeps information about the version, such as the author, the
committer, a message describing the snapshot, and the commit objects of the snapshots
immediately before the current snapshot.

The normal workflow using a locally stored versions is as follows.

Checkout the project:

git checkout master

Work on the project.

Track the changed files:
git add .

Commit the tracked files:

git commit -m "commit message"

To check to see all commits:

git log --graph --pretty=oneline

When work with collaborators using a remote repo, Stick to the following workflow.

Pull the remote repo into current working directory:

git pull origin

If Git shows conflicts, manually resolve them.

Follow the local workflow until your task is completed.
Pull the remote repo gain:
 git pull origin

Resolve any conflict.

Push the project back to remote repo:
git push origin master

Git Branches

The history of a project often starts from a single base and at some point of time, branches
out in different directions to test alternative ideas, and later on merges branches back into
the main direction. At some point the project is ready for a major release. Git provides
commands to manage branches.

A Git branch is a pointer to the most recent commit object of the branch. The default main
branch is the master. User can create new branch using command. For example,
git checkout -b b1

will create a new branch b1 out of the current branch (assuming this is the first user
defined branch, then the current branch is the master). Git also has a point named HEAD
that always points to the current commit object. After the previous command, the pointers
b1, master and HEAD all point to the same commit. However, after the next commit
command, the master will stay at the same place, but both b1 and HEAD will point
(advanced) to the new commit. If at this time, we enter the command
git checkout master

The HEAD will go back to where the master was and leave b1 alone at the new commit in
the new branch. Enter another commit command will advance both the master and the
HEAD to a new third commit. At this time, the master and the b1 branches are heading
different ways.

To merge two branches, one needs to checkout the destination branch, say master, with

git checkout master

and then merge the source branch, say b2, into the destination branch with
git merge b2

This will try to merge files from master and b2 branches together into a new consistent
snapshot. However, if there are conflicts in the files, Git will show the differences in the two
branches, and ask users to manually resolve all conflicts before commit. Once the merge is
completed successfully, a new commit is created for the merged snapshot. An experiment to
show how Git branch works can be found in here. A similar experiment using EGit that
comes with Eclipse is given in here.

Work with Remote Repo

A remote repo changes only when users push their individual versions to the server. So, it is
more often than not our local version is different from the remote repo. In addition, every
team member can set up their own server to host a version of the same project (thus
provide a distributed version control). So, there can be multiple remote repos.
At the local computer, the Git can remember the current remote repo. The default local
name of the remote repo is origin and the default local name of the remote branch is
remotes/origin/master. A local commit will not advance remotes/origin/master (it always
points to the version that was most recently cloned or pulled). Several Git commands can be
used to work with remote repos.

Set default origin:

git remote add origin git://github.com/utsa-cs3443-zhang/proj.git

Rename a remote repo:

git remote rename origin myrepo

Remove a remote repo:

git remote rm myrepo

Show all locally known remote repos:

git remote show

and
git remote -v

Fetch remote repo:

git fetch origin

Pull remote repo:

git pull origin

Push to remote repo:

git push origin master

Each remote repo is identified by an URL. The format is

[protocol]://[server URL]/[repo path]

The protocol include git, ssh, and https. The fetch command will obtain the remote repo, but
not merge it with the local version. The pull command will fetch and attempt a merge. The
push command can push any local branch to any remote repo. Both pull and push may ask
you to resolve conflict before complete their tasks.

Work with GitHub

GitHub is one of several websites that provide cloud storage and management of Git repos.
Everyone can register for a free account. Once registered, a user can manage their own
public repos and join the teams on private repos. Sudents of this course can join teams of
private project repos belong to an organization named utsa-cs3443-zhang. To work with
project Git repos, students should do the following.

Register an account on GitHub

Upload their ssh public keys from the computers they want to use to clone, pull and
push remote repos.
 Email their GitHub user names to the instructor so that they can be added to project
teams.

Once added to a team and given an access to a remote repo, a student will receive an email
from GitHub. Also, at the next log-in to GitHub, the student should be able to see the
accessible repos. In the home page of the repo, there is the URL of the repo, which can be
used in the git command to clone the repo.

Work with Git-GUI and Gitk

The standard GUI for Git is the Git-GUI and GitK. The Git-GUI can be started from the
desktop. For example, in Fedora Linux, click on
Applications->Programming->Git

It will ask you to specify a directory that contains the local Git repo. The menu items directly
correspond to Git commands discussed previously. To view the history of the project, click
Repository->Visualize All Branch History

This will start the GitK. Another way to start the GUI is to go to the project directory, and
enter the command gitk. Then, in the GitK window, click
File->Start git gui

Work with EGit

See the Hints for Using EGit.