-A short git tutorial
-====================
+A git core tutorial for developers
+==================================
Introduction
------------
For our first example, we're going to start a totally new repository from
scratch, with no pre-existing files, and we'll call it `git-tutorial`.
To start up, create a subdirectory for it, change into that
-subdirectory, and initialize the git infrastructure with `git-init-db`:
+subdirectory, and initialize the git infrastructure with `git-init`:
------------------------------------------------
$ mkdir git-tutorial
$ cd git-tutorial
-$ git-init-db
+$ git-init
------------------------------------------------
to which git will reply
----------------
-defaulting to local storage area
+Initialized empty Git repository in .git/
----------------
which is just git's way of saying that you haven't been doing anything
inspect that with `ls`. For your new empty project, it should show you
three entries, among other things:
- - a symlink called `HEAD`, pointing to `refs/heads/master` (if your
- platform does not have native symlinks, it is a file containing the
- line "ref: refs/heads/master")
+ - a file called `HEAD`, that has `ref: refs/heads/master` in it.
+ This is similar to a symbolic link and points at
+ `refs/heads/master` relative to the `HEAD` file.
+
Don't worry about the fact that the file that the `HEAD` link points to
doesn't even exist yet -- you haven't created the commit that will
repository.
One note: the special `master` head is the default branch, which is
-why the `.git/HEAD` file was created as a symlink to it even if it
+why the `.git/HEAD` file was created points to it even if it
doesn't yet exist. Basically, the `HEAD` link is supposed to always
point to the branch you are working on right now, and you always
start out expecting to work on the `master` branch.
$ echo "Silly example" >example
------------------------------------------------
-you have now created two files in your working tree (aka 'working directory'), but to
-actually check in your hard work, you will have to go through two steps:
+you have now created two files in your working tree (aka 'working directory'),
+but to actually check in your hard work, you will have to go through two steps:
- fill in the 'index' file (aka 'cache') with the information about your
working tree state.
.git/objects/f2/4c74a2e500f5ee1332c86b94199f52b1d1d962
----------------
-which correspond with the objects with names of 557db... and f24c7..
-respectively.
+which correspond with the objects with names of `557db...` and
+`f24c7...` respectively.
If you want to, you can use `git-cat-file` to look at those objects, but
you'll have to use the object name, not the filename of the object:
----------------
where the `-t` tells `git-cat-file` to tell you what the "type" of the
-object is. git will tell you that you have a "blob" object (ie just a
+object is. git will tell you that you have a "blob" object (i.e., just a
regular file), and you can see the contents with
----------------
$ git-cat-file "blob" 557db03
----------------
-which will print out "Hello World". The object 557db03 is nothing
+which will print out "Hello World". The object `557db03` is nothing
more than the contents of your file `hello`.
[NOTE]
$ git-update-ref HEAD $commit
------------------------------------------------
-which will say:
-
-----------------
-Committing initial tree 8988da15d077d4829fc51d8544c097def6644dbb
-----------------
-
-just to warn you about the fact that it created a totally new commit
-that is not related to anything else. Normally you do this only *once*
-for a project ever, and all later commits will be parented on top of an
-earlier commit, and you'll never see this "Committing initial tree"
-message ever again.
+In this case this creates a totally new commit that is not related to
+anything else. Normally you do this only *once* for a project ever, and
+all later commits will be parented on top of an earlier commit.
Again, normally you'd never actually do this by hand. There is a
helpful script called `git commit` that will do all of this for you. So
+-----------+
============
-More interestingly, you can also give `git-diff-tree` the `-v` flag, which
-tells it to also show the commit message and author and date of the
+More interestingly, you can also give `git-diff-tree` the `--pretty` flag,
+which tells it to also show the commit message and author and date of the
commit, and you can tell it to show a whole series of diffs.
Alternatively, you can tell it to be "silent", and not show the diffs at
all, but just show the actual commit message.
----------------
which will sign the current `HEAD` (but you can also give it another
-argument that specifies the thing to tag, ie you could have tagged the
+argument that specifies the thing to tag, i.e., you could have tagged the
current `mybranch` point by using `git tag <tagname> mybranch`).
You normally only do signed tags for major releases or things
Copying repositories
--------------------
-git repositories are normally totally self-sufficient and relocatable
+git repositories are normally totally self-sufficient and relocatable.
Unlike CVS, for example, there is no separate notion of
"repository" and "working tree". A git repository normally *is* the
working tree, with the local git information hidden in the `.git`
(or any other branch-name, for that matter) and if you forget which
branch you happen to be on, a simple
-------------
-$ ls -l .git/HEAD
-------------
-
-will tell you where it's pointing (Note that on platforms with bad or no
-symlink support, you have to execute
-
------------
$ cat .git/HEAD
------------
-instead). To get the list of branches you have, you can say
+will tell you where it's pointing. To get the list of branches
+you have, you can say
------------
$ git branch
------------------------------------------------
$ git checkout mybranch
$ echo "Work, work, work" >>hello
-$ git commit -m 'Some work.' hello
+$ git commit -m 'Some work.' -i hello
------------------------------------------------
Here, we just added another line to `hello`, and we used a shorthand for
doing both `git-update-index hello` and `git commit` by just giving the
-filename directly to `git commit`. The `-m` flag is to give the
+filename directly to `git commit`, with an `-i` flag (it tells
+git to 'include' that file in addition to what you have done to
+the index file so far when making the commit). The `-m` flag is to give the
commit log message from the command line.
Now, to make it a bit more interesting, let's assume that somebody else
------------
$ echo "Play, play, play" >>hello
$ echo "Lots of fun" >>example
-$ git commit -m 'Some fun.' hello example
+$ git commit -m 'Some fun.' -i hello example
------------
since the master branch is obviously in a much better mood.
file, which had no differences in the `mybranch` branch), and say:
----------------
- Trying really trivial in-index merge...
- fatal: Merge requires file-level merging
- Nope.
- ...
Auto-merging hello
CONFLICT (content): Merge conflict in hello
- Automatic merge failed/prevented; fix up by hand
+ Automatic merge failed; fix up by hand
----------------
-which is way too verbose, but it basically tells you that it failed the
-really trivial merge ("Simple merge") and did an "Automatic merge"
-instead, but that too failed due to conflicts in `hello`.
+It tells you that it did an "Automatic merge", which
+failed due to conflicts in `hello`.
Not to worry. It left the (trivial) conflict in `hello` in the same form you
should already be well used to if you've ever used CVS, so let's just
and once you're happy with your manual merge, just do a
------------
-$ git commit hello
+$ git commit -i hello
------------
which will very loudly warn you that you're now committing a merge
environment, is `git show-branch`.
------------------------------------------------
-$ git show-branch master mybranch
+$ git show-branch --topo-order master mybranch
* [master] Merge work in mybranch
! [mybranch] Some work.
--
The first two lines indicate that it is showing the two branches
and the first line of the commit log message from their
top-of-the-tree commits, you are currently on `master` branch
-(notice the asterisk `*` character), and the first column for
+(notice the asterisk `\*` character), and the first column for
the later output lines is used to show commits contained in the
`master` branch, and the second column for the `mybranch`
branch. Three commits are shown along with their log messages.
----------------
Updating from ae3a2da... to a80b4aa....
+Fast forward
example | 1 +
hello | 1 +
2 files changed, 2 insertions(+), 0 deletions(-)
using the object name of that commit object. Then it reads the
commit object to find out its parent commits and the associate
tree object; it repeats this process until it gets all the
-necessary objects. Because of this behaviour, they are
+necessary objects. Because of this behavior, they are
sometimes also called 'commit walkers'.
+
The 'commit walkers' are sometimes also called 'dumb
keeping as many local repositories as you would like to have
branches, and merging between them with `git pull`, just like
you merge between branches. The advantage of this approach is
-that it lets you keep set of files for each `branch` checked
+that it lets you keep a set of files for each `branch` checked
out and you may find it easier to switch back and forth if you
juggle multiple lines of development simultaneously. Of
course, you will pay the price of more disk usage to hold
multiple working trees, but disk space is cheap these days.
-[NOTE]
-You could even pull from your own repository by
-giving '.' as <remote-repository> parameter to `git pull`. This
-is useful when you want to merge a local branch (or more, if you
-are making an Octopus) into the current branch.
-
It is likely that you will be pulling from the same remote
repository from time to time. As a short hand, you can store
-the remote repository URL in a file under .git/remotes/
-directory, like this:
-
-------------------------------------------------
-$ mkdir -p .git/remotes/
-$ cat >.git/remotes/linus <<\EOF
-URL: http://www.kernel.org/pub/scm/git/git.git/
-EOF
-------------------------------------------------
-
-and use the filename to `git pull` instead of the full URL.
-The URL specified in such file can even be a prefix
-of a full URL, like this:
+the remote repository URL in the local repository's config file
+like this:
------------------------------------------------
-$ cat >.git/remotes/jgarzik <<\EOF
-URL: http://www.kernel.org/pub/scm/linux/git/jgarzik/
-EOF
+$ git config remote.linus.url http://www.kernel.org/pub/scm/git/git.git/
------------------------------------------------
+and use the "linus" keyword with `git pull` instead of the full URL.
Examples.
. `git pull linus`
. `git pull linus tag v0.99.1`
-. `git pull jgarzik/netdev-2.6.git/ e100`
the above are equivalent to:
. `git pull http://www.kernel.org/pub/scm/git/git.git/ HEAD`
. `git pull http://www.kernel.org/pub/scm/git/git.git/ tag v0.99.1`
-. `git pull http://www.kernel.org/pub/.../jgarzik/netdev-2.6.git e100`
How does the merge work?
Publishing your work
--------------------
-So we can use somebody else's work from a remote repository; but
+So, we can use somebody else's work from a remote repository, but
how can *you* prepare a repository to let other people pull from
it?
------------
Then, make that directory into a git repository by running
-`git init-db`, but this time, since its name is not the usual
+`git init`, but this time, since its name is not the usual
`.git`, we do things slightly differently:
------------
-$ GIT_DIR=my-git.git git-init-db
+$ GIT_DIR=my-git.git git-init
------------
Make sure this directory is available for others you want your
Although git is a truly distributed system, it is often
convenient to organize your project with an informal hierarchy
of developers. Linux kernel development is run this way. There
-is a nice illustration (page 17, "Merges to Mainline") in Randy
-Dunlap's presentation (`http://tinyurl.com/a2jdg`).
+is a nice illustration (page 17, "Merges to Mainline") in
+link:http://tinyurl.com/a2jdg[Randy Dunlap's presentation].
It should be stressed that this hierarchy is purely *informal*.
There is nothing fundamental in git that enforces the "chain of
+
If other people are pulling from your repository over dumb
transport protocols (HTTP), you need to keep this repository
-'dumb transport friendly'. After `git init-db`,
+'dumb transport friendly'. After `git init`,
`$GIT_DIR/hooks/post-update` copied from the standard templates
would contain a call to `git-update-server-info` but the
`post-update` hook itself is disabled by default -- enable it
1. Prepare your work repository, by `git clone` the public
repository of the "project lead". The URL used for the
- initial cloning is stored in `.git/remotes/origin`.
+ initial cloning is stored in the remote.origin.url
+ configuration variable.
2. Prepare a public repository accessible to others, just like
the "project lead" person does.
1. Prepare your work repository, by `git clone` the public
repository of the "project lead" (or a "subsystem
maintainer", if you work on a subsystem). The URL used for
- the initial cloning is stored in `.git/remotes/origin`.
+ the initial cloning is stored in the remote.origin.url
+ configuration variable.
2. Do your work in your repository on 'master' branch.
3. Run `git fetch origin` from the public repository of your
upstream every once in a while. This does only the first
half of `git pull` but does not merge. The head of the
- public repository is stored in `.git/refs/heads/origin`.
+ public repository is stored in `.git/refs/remotes/origin/master`.
4. Use `git cherry origin` to see which ones of your patches
were accepted, and/or use `git rebase origin` to port your
have to worry. git supports "shared public repository" style of
cooperation you are probably more familiar with as well.
-See link:cvs-migration.txt[git for CVS users] for the details.
+See link:cvs-migration.html[git for CVS users] for the details.
Bundling your work together
---------------------------
You can make sure 'git show-branch' matches the state before
those two 'git merge' you just did. Then, instead of running
-two 'git merge' commands in a row, you would pull these two
+two 'git merge' commands in a row, you would merge these two
branch heads (this is known as 'making an Octopus'):
------------
-$ git pull . commit-fix diff-fix
+$ git merge commit-fix diff-fix
$ git show-branch
! [commit-fix] Fix commit message normalization.
! [diff-fix] Fix rename detection.
Note that you should not do Octopus because you can. An octopus
is a valid thing to do and often makes it easier to view the
-commit history if you are pulling more than two independent
+commit history if you are merging more than two independent
changes at the same time. However, if you have merge conflicts
with any of the branches you are merging in and need to hand
resolve, that is an indication that the development happened in