-A tutorial introduction to git
-==============================
+A tutorial introduction to git (for version 1.5.1 or newer)
+===========================================================
This tutorial explains how to import a new project into git, make
changes to it, and share changes with other developers.
+If you are instead primarily interested in using git to fetch a project,
+for example, to test the latest version, you may prefer to start with
+the first two chapters of link:user-manual.html[The Git User's Manual].
+
First, note that you can get documentation for a command such as "git
diff" with:
$ man git-diff
------------------------------------------------
-It is a good idea to introduce yourself to git before doing any
-operation. The easiest way to do so is:
+It is a good idea to introduce yourself to git with your name and
+public email address before doing any operation. The easiest
+way to do so is:
------------------------------------------------
-$ cat >~/.gitconfig <<\EOF
-[user]
- name = Your Name Comes Here
- email = you@yourdomain.example.com
-EOF
+$ git config --global user.name "Your Name Comes Here"
+$ git config --global user.email you@yourdomain.example.com
------------------------------------------------
------------------------------------------------
$ tar xzf project.tar.gz
$ cd project
-$ git init-db
+$ git init
------------------------------------------------
Git will reply
------------------------------------------------
-defaulting to local storage area
+Initialized empty Git repository in .git/
------------------------------------------------
You've now initialized the working directory--you may notice a new
-directory created, named ".git". Tell git that you want it to track
-every file under the current directory with (notice the dot '.'
-that means the current directory):
+directory created, named ".git".
+
+Next, tell git to take a snapshot of the contents of all files under the
+current directory (note the '.'), with gitlink:git-add[1]:
------------------------------------------------
$ git add .
------------------------------------------------
-Finally,
+This snapshot is now stored in a temporary staging area which git calls
+the "index". You can permanently store the contents of the index in the
+repository with gitlink:git-commit[1]:
------------------------------------------------
$ git commit
------------------------------------------------
-will prompt you for a commit message, then record the current state
-of all the files to the repository.
+This will prompt you for a commit message. You've now stored the first
+version of your project in git.
-Try modifying some files, then run
+Making changes
+--------------
+
+Modify some files, then add their updated contents to the index:
------------------------------------------------
-$ git diff
+$ git add file1 file2 file3
------------------------------------------------
-to review your changes. When you're done,
+You are now ready to commit. You can see what is about to be committed
+using gitlink:git-diff[1] with the --cached option:
------------------------------------------------
-$ git commit file1 file2...
+$ git diff --cached
------------------------------------------------
-will again prompt your for a message describing the change, and then
-record the new versions of the files you listed. It is cumbersome
-to list all files and you can say `-a` (which stands for 'all')
-instead.
+(Without --cached, gitlink:git-diff[1] will show you any changes that
+you've made but not yet added to the index.) You can also get a brief
+summary of the situation with gitlink:git-status[1]:
+
+------------------------------------------------
+$ git status
+# On branch master
+# Changes to be committed:
+# (use "git reset HEAD <file>..." to unstage)
+#
+# modified: file1
+# modified: file2
+# modified: file3
+#
+------------------------------------------------
+
+If you need to make any further adjustments, do so now, and then add any
+newly modified content to the index. Finally, commit your changes with:
+
+------------------------------------------------
+$ git commit
+------------------------------------------------
+
+This will again prompt your for a message describing the change, and then
+record a new version of the project.
+
+Alternatively, instead of running `git add` beforehand, you can use
------------------------------------------------
$ git commit -a
------------------------------------------------
+which will automatically notice any modified (but not new) files, add
+them to the index, and commit, all in one step.
+
A note on commit messages: Though not required, it's a good idea to
begin the commit message with a single short (less than 50 character)
line summarizing the change, followed by a blank line and then a more
thorough description. Tools that turn commits into email, for
-example, use the first line on the Subject line and the rest of the
+example, use the first line on the Subject: line and the rest of the
commit in the body.
-
Git tracks content not files
----------------------------
-With git you have to explicitly "add" all the changed _content_ you
-want to commit together. This can be done in a few different ways:
-
-1) By using 'git add <file_spec>...'
-
- This can be performed multiple times before a commit. Note that this
- is not only for adding new files. Even modified files must be
- added to the set of changes about to be committed. The "git status"
- command gives you a summary of what is included so far for the
- next commit. When done you should use the 'git commit' command to
- make it real.
-
- Note: don't forget to 'add' a file again if you modified it after the
- first 'add' and before 'commit'. Otherwise only the previous added
- state of that file will be committed. This is because git tracks
- content, so what you're really 'add'ing to the commit is the *content*
- of the file in the state it is in when you 'add' it.
-
-2) By using 'git commit -a' directly
-
- This is a quick way to automatically 'add' the content from all files
- that were modified since the previous commit, and perform the actual
- commit without having to separately 'add' them beforehand. This will
- not add content from new files i.e. files that were never added before.
- Those files still have to be added explicitly before performing a
- commit.
-
-But here's a twist. If you do 'git commit <file1> <file2> ...' then only
-the changes belonging to those explicitly specified files will be
-committed, entirely bypassing the current "added" changes. Those "added"
-changes will still remain available for a subsequent commit though.
-
-However, for normal usage you only have to remember 'git add' + 'git commit'
-and/or 'git commit -a'.
-
+Many revision control systems provide an "add" command that tells the
+system to start tracking changes to a new file. Git's "add" command
+does something simpler and more powerful: `git add` is used both for new
+and newly modified files, and in both cases it takes a snapshot of the
+given files and stages that content in the index, ready for inclusion in
+the next commit.
-Viewing the changelog
----------------------
+Viewing project history
+-----------------------
At any point you can view the history of your changes using
$ git log -p
------------------------------------------------
+Often the overview of the change is useful to get a feel of
+each step
+
+------------------------------------------------
+$ git log --stat --summary
+------------------------------------------------
+
Managing branches
-----------------
made in each. To merge the changes made in experimental into master, run
------------------------------------------------
-$ git pull . experimental
+$ git merge experimental
------------------------------------------------
If the changes don't conflict, you're done. If there are conflicts,
will show a nice graphical representation of the resulting history.
+At this point you could delete the experimental branch with
+
+------------------------------------------------
+$ git branch -d experimental
+------------------------------------------------
+
+This command ensures that the changes in the experimental branch are
+already in the current branch.
+
If you develop on a branch crazy-idea, then regret it, you can always
delete the branch with
The "pull" command thus performs two operations: it fetches changes
from a remote branch, then merges them into the current branch.
-You can perform the first operation alone using the "git fetch"
-command. For example, Alice could create a temporary branch just to
-track Bob's changes, without merging them with her own, using:
+When you are working in a small closely knit group, it is not
+unusual to interact with the same repository over and over
+again. By defining 'remote' repository shorthand, you can make
+it easier:
+
+------------------------------------------------
+$ git remote add bob /home/bob/myrepo
+------------------------------------------------
+
+With this, you can perform the first operation alone using the
+"git fetch" command without merging them with her own branch,
+using:
-------------------------------------
-$ git fetch /home/bob/myrepo master:bob-incoming
+$ git fetch bob
-------------------------------------
-which fetches the changes from Bob's master branch into a new branch
-named bob-incoming. Then
+Unlike the longhand form, when Alice fetches from Bob using a
+remote repository shorthand set up with `git remote`, what was
+fetched is stored in a remote tracking branch, in this case
+`bob/master`. So after this:
-------------------------------------
-$ git log -p master..bob-incoming
+$ git log -p master..bob/master
-------------------------------------
shows a list of all the changes that Bob made since he branched from
Alice's master branch.
-After examining those changes, and possibly fixing things, Alice
-could pull the changes into her master branch:
+After examining those changes, Alice
+could merge the changes into her master branch:
-------------------------------------
-$ git checkout master
-$ git pull . bob-incoming
+$ git merge bob/master
-------------------------------------
-The last command is a pull from the "bob-incoming" branch in Alice's
-own repository.
-
-Alice could also perform both steps at once with:
+This `merge` can also be done by 'pulling from her own remote
+tracking branch', like this:
-------------------------------------
-$ git pull /home/bob/myrepo master:bob-incoming
+$ git pull . remotes/bob/master
-------------------------------------
-This is just like the "git pull /home/bob/myrepo master" that we saw
-before, except that it also stores the unmerged changes from bob's
-master branch in bob-incoming before merging them into Alice's
-current branch. Note that git pull always merges into the current
-branch, regardless of what else is given on the commandline.
+Note that git pull always merges into the current branch,
+regardless of what else is given on the commandline.
Later, Bob can update his repo with Alice's latest changes using
Note that he doesn't need to give the path to Alice's repository;
when Bob cloned Alice's repository, git stored the location of her
-repository in the file .git/remotes/origin, and that location is used
-as the default for pulls.
-
-Bob may also notice a branch in his repository that he didn't create:
+repository in the repository configuration, and that location is
+used for pulls:
-------------------------------------
-$ git branch
-* master
- origin
+$ git config --get remote.origin.url
+/home/bob/myrepo
-------------------------------------
-The "origin" branch, which was created automatically by "git clone",
-is a pristine copy of Alice's master branch; Bob should never commit
-to it.
+(The complete configuration created by git-clone is visible using
+"git config -l", and the gitlink:git-config[1] man page
+explains the meaning of each option.)
+
+Git also keeps a pristine copy of Alice's master branch under the
+name "origin/master":
+
+-------------------------------------
+$ git branch -r
+ origin/master
+-------------------------------------
If Bob later decides to work from a different host, he can still
perform clones and pulls using the ssh protocol:
$ git show c82a22c39cbc32576f64f5c6b3f24b99ea8149c7
-------------------------------------
-But there other ways to refer to commits. You can use any initial
+But there are other ways to refer to commits. You can use any initial
part of the name that is long enough to uniquely identify the commit:
-------------------------------------
$ git show experimental # the tip of the "experimental" branch
-------------------------------------
-Every commit has at least one "parent" commit, which points to the
-previous state of the project:
+Every commit usually has one "parent" commit
+which points to the previous state of the project:
-------------------------------------
$ git show HEAD^ # to see the parent of HEAD
Be careful with that last command: in addition to losing any changes
in the working directory, it will also remove all later commits from
this branch. If this branch is the only branch containing those
-commits, they will be lost. (Also, don't use "git reset" on a
-publicly-visible branch that other developers pull from, as git will
-be confused by history that disappears in this way.)
+commits, they will be lost. Also, don't use "git reset" on a
+publicly-visible branch that other developers pull from, as it will
+force needless merges on other developers to clean up the history.
+If you need to undo changes that you have pushed, use gitlink:git-revert[1]
+instead.
The git grep command can search for strings in any version of your
project, so
$ git diff v2.5:Makefile HEAD:Makefile.in
-------------------------------------
-You can also use "git cat-file -p" to see any such file:
+You can also use "git show" to see any such file:
-------------------------------------
-$ git cat-file -p v2.5:Makefile
+$ git show v2.5:Makefile
-------------------------------------
Next Steps
database, the index file, and a few other odds and ends that you'll
need to make the most of git.
-If you don't want to consider with that right away, a few other
+If you don't want to continue with that right away, a few other
digressions that may be interesting at this point are:
* gitlink:git-format-patch[1], gitlink:git-am[1]: These convert