Overview

Git is a distributed version control system developed by Linus Torvalds. It is used for managing Linux kernel development as well as for many other projects.

There is a variety of good information about Git available online, including The official Git documentation, which includes both a tutorial and a complete reference manual with links to individual subcommand documentation.

Getting Started

Getting help

Most commands have built-in documentation you can access with the --help option:

$ git init --help

You can generally access the same documentation as Unix man pages, e.g:

man git-init

Creating a repository

Use git init to create a git repository in your current directory:

$ mkdir myproject
$ cd myproject
$ git init

git init creates a git repository in your current working directory. You will add files to this repository using git add. This gives you a repository (the .git directory) and a working copy (everything else).

Tracking an Existing Project

If you are going to start tracking an existing project with git, you will generally start like this:

$ cd myproject
$ git init

This initializes the repository. Next, add the existing files to the repository:

$ git add .
$ git commit -m 'initial import'

Adding files

The git add command schedules files to be committed to the repository.

$ git add file1.py file2.py.c

Unlike Subversion, if you modify a file you (generally) need to git add that file in order to make the changes part of the next commit.

Use the git reset command to "undo" an add operation:

$ git reset HEAD

This resets the index but leaves your working directory untouched. You can also use git reset to revert to a previous commit; read the documentation for more information.

Committing changes

Use git commit to commit files to your local repository:

$ git commit

The command git commit by itself will commit any changes scheduled using git add. If you would like to commit all locally modified files, use the -a option:

$ git commit -a

You may also commit a subset of modified files by specifying paths on the
command line:

$ git commit path/to/modified/file

Managing Files

Renaming files

Use git mv to rename files in the repository:

$ git mv oldname newname

Because git tracks files by cryptographic checksum, rather than by name, the git mv command is not strictly necessary. If you manually rename a file and then do a git rm file followed by a git add file, git will correctly recognize that you have simply renamed it (because the checksum is still the same).

Removing files

Use git rm to remove files from the repository:

$ git rm file1.py

What's changed: status

Use git status to see a list of modified files:

$ git status

The output of git status will look something like this:

$ git status
# On branch master
# Changed but not updated:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#  modified:   version-control.rst
#
# Untracked files:
#   (use "git add <file>..." to include in what will be committed)
#
#  examples/
no changes added to commit (use "git add" and/or "git commit -a")

The files listed as "changed but not updated" are files that you have modified but not yet added to the repository. "Untracked files" are files that have not previously been added to the repository.

What's changed: diffs

Use git diff to see pending changes in your working copy:

$ git diff

The output of git diff is standard diff output, e.g.:

$ git diff
diff --git a/version-control.rst b/version-control.rst
index e518192..b1c519a 100644
--- a/version-control.rst
+++ b/version-control.rst
@@ -243,6 +243,34 @@ commit`` to commit them to the (local) repository::
 Using git: What's changed?
 ==========================

+Use ``git status`` to see a list of modified files::
+
+  git status
+
+.. container:: handout
+
+   The output will look something like this::
+

You can also use git diff to see the changes between arbitrary revisions of your project:

Changes in working copy vs. previous commit:
```
git diff <commit>
```

-Changes between two previous commits:

git diff <commit1> <commit2>

Working With Remote Repositories

Cloning a Remote Repository

Use the git clone command to check out a working copy of a remote repository:

$ git clone REPOSITORY [DIRECTORY]

The command git clone will clone the remote repository to a new directory in your current directory named after the repository, unless you explicitly provide a name with the DIRECTORY argument.

Updating your working copy

Use git pull to update your local repository from the remote repository and merge changes into your working copy:

$ git pull [REPOSITORY [REFSPEC]]

git pull by itself will pull changes from the remote repository defined by the branch.master.remote config option (which will typically be the repository from which you originally cloned your working copy). If there are multiple remote repositories associated with your working copy, you can specify a repository (and branch) on the command line, e.g, to pull changes from the branch master at a remote named origin:

$ git pull origin master

Pushing changes

Use git push to send your committed changes to a remote repository:

$ git push [REPOSITORY [REFSPEC]]

git push by itself will push your changes to the remote repository defined by the branch.master.remote config option (which will typically be the repository from which you originally cloned your working copy). If there are multiple remote repositories associated with your working copy, you can specify a repository (and branch) on the command line, e.g, to push your changes to branch master at a remote named origin:

$ git push origin master

If you attempt to push to a repository that is newer than your working copy you will see an error similar to the following:

$ git push
To code.harvard.edu:repos/myproject
 ! [rejected]        master -> master (non-fast forward)
error: failed to push some refs to 'code.harvard.edu:repos/myproject'
To fix this, run git pull and deal with any conflicts.

To fix this, you need to pull from that repo, merge changes, and then push.

Sharing your repository

If you will be sharing a repository with others (or with yourself on multiple computers), you will need to create a "bare" repository – that is, a repository without a working copy. You do this with the -b flag to git init:

$ git init -b

You can then clone this repository, pull from it, and push to it as described in the previous section.

Conflicts

A conflict occurrs when two people make overlapping changes.

They are detected when you attempt to update your working copy via git pull.
You may discard your changes, discard the repository changes, or attempt to correct things manually. If you attempt to pull in changes that conflict with your working tree, you will see an error similar to the following:

$ git pull
remote: Counting objects: 5, done.
remote: Compressing objects: 100% (3/3), done.
remote: Total 3 (delta 2), reused 0 (delta 0)
Unpacking objects: 100% (3/3), done.
From /Users/testuser/projects/repo
   4245cb6..84f1112  master     -> origin/master
Auto-merging README
CONFLICT (content): Merge conflict in README
Automatic merge failed; fix conflicts and then commit the result.

To resolve the conflict manually:

Edit the conflicting files as necessary.

To discard your changes (and accept the remote repository version):

run git checkout --theirs README

To override the repository with your changes:

run git checkout --ours README

When you complete the above tasks:

add the files with git add
commit the changes with git commit.

Log, Tags, and Branches

Viewing history

The git log command shows you the history of your repository:

$ git log [PATH]

git log with no arguments shows you the commit messages for each revision in your repository:

$ git log
commit 7c8c3e71893d7481fdd9c13ec8f53cb9c61fac50
Author: testuser lastname  <testuser@g.harvard.edu>
Date:   Tue Sep 18 12:46:46 2018 -0400

    changed GNU to Microsoft

commit 257f2f3ff44c2165c1182d3673a825fcadf121aa
Author: testuser lastname  <testuser@g.harvard.edu>
Date:   Tue Sep 18 12:46:46 2018 -0400

    made a change

commit 99c4fb8f37e48284d79c7396aaf755b514d6a249
Author: testuser lastname  <testuser@g.harvard.edu>
Date:   Tue Sep 18 12:46:45 2018 -0400

    made some changes

commit 20cc63576f7c88541f5b9471e20f4d1c5f8afcb9
Author: testuser lastname  <testuser@g.harvard.edu>
Date:   Tue Sep 18 12:46:45 2018 -0400

    initial import

Tagging and branching

Git has explicit support for tagging and branching.

git tag manipulates tags
git branch and git checkout manipulate branches

Branches

List branches:

$ git branch

Create a new branch:

$ git checkout -b BRANCHNAME

To switch to a branch:

$ git checkout BRANCHNAME

For example, you want to enhance your code with some awesome experimental code. You create a new "dev" branch and switch to it:

$ git checkout -b dev

You make some changes, and when things are working you commit your branch:

$ git commit -m 'made some awesome changes' -a

And then merge it into the master branch:

$ git checkout master
$ git merge dev
Updating 1288ed3..33e4a4c
Fast-forward
 version-control.rst |    2 ++
 1 files changed, 2 insertions(+), 0 deletions(-)

The Git Index

Git is not really just like Subversion (or most other version control solutions). That's mainly because of the git "index".

The index is a staging area between your working copy and your local repository.
git add adds files to the index
git commit commits files from the index to the repository.

The diff commands uses the index:

git diff is the difference between your working copy and the index.
git diff HEAD is the difference between your working copy and the local repository.
git diff --cached is the difference between the index and the local repository.

Refer back to this illustration if you get confused:

GIT Version Control