NAME
----
-gitcore-tutorial - A git core tutorial for developers
+gitcore-tutorial - A Git core tutorial for developers
SYNOPSIS
--------
DESCRIPTION
-----------
-This tutorial explains how to use the "core" git commands to set up and
-work with a git repository.
+This tutorial explains how to use the "core" Git commands to set up and
+work with a Git repository.
-If you just need to use git as a revision control system you may prefer
-to start with "A Tutorial Introduction to GIT" (linkgit:gittutorial[7]) or
-link:user-manual.html[the GIT User Manual].
+If you just need to use Git as a revision control system you may prefer
+to start with "A Tutorial Introduction to Git" (linkgit:gittutorial[7]) or
+link:user-manual.html[the Git User Manual].
However, an understanding of these low-level tools can be helpful if
-you want to understand git's internals.
+you want to understand Git's internals.
-The core git is often called "plumbing", with the prettier user
+The core Git is often called "plumbing", with the prettier user
interfaces on top of it called "porcelain". You may not want to use the
plumbing directly very often, but it can be good to know what the
plumbing does for when the porcelain isn't flushing.
skip on your first reading.
-Creating a git repository
+Creating a Git repository
-------------------------
-Creating a new git repository couldn't be easier: all git repositories start
+Creating a new Git repository couldn't be easier: all Git repositories start
out empty, and the only thing you need to do is find yourself a
subdirectory that you want to use as a working tree - either an empty
one for a totally new project, or an existing working tree that you want
-to import into git.
+to import into Git.
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':
+subdirectory, and initialize the Git infrastructure with 'git init':
------------------------------------------------
$ mkdir git-tutorial
$ git init
------------------------------------------------
-to which git will reply
+to which Git will reply
----------------
Initialized empty Git repository in .git/
----------------
-which is just git's way of saying that you haven't been doing anything
+which is just Git's way of saying that you haven't been doing anything
strange, and that it will have created a local `.git` directory setup for
your new project. You will now have a `.git` directory, and you can
inspect that with 'ls'. For your new empty project, it should show you
However, this is only a convention, and you can name your branches
anything you want, and don't have to ever even 'have' a `master`
-branch. A number of the git tools will assume that `.git/HEAD` is
+branch. A number of the Git tools will assume that `.git/HEAD` is
valid, though.
[NOTE]
-An 'object' is identified by its 160-bit SHA1 hash, aka 'object name',
+An 'object' is identified by its 160-bit SHA-1 hash, aka 'object name',
and a reference to an object is always the 40-byte hex
-representation of that SHA1 name. The files in the `refs`
+representation of that SHA-1 name. The files in the `refs`
subdirectory are expected to contain these hex references
(usually with a final `\n` at the end), and you should thus
expect to see a number of 41-byte files containing these
An advanced user may want to take a look at linkgit:gitrepository-layout[5]
after finishing this tutorial.
-You have now created your first git repository. Of course, since it's
+You have now created your first Git repository. Of course, since it's
empty, that's not very useful, so let's start populating it with data.
-Populating a git repository
+Populating a Git repository
---------------------------
We'll keep this simple and stupid, so we'll start off with populating a
few trivial files just to get a feel for it.
Start off with just creating any random files that you want to maintain
-in your git repository. We'll start off with a few bad examples, just to
+in your Git repository. We'll start off with a few bad examples, just to
get a feel for how this works:
------------------------------------------------
- commit that index file as an object.
-The first step is trivial: when you want to tell git about any changes
+The first step is trivial: when you want to tell Git about any changes
to your working tree, you use the 'git update-index' program. That
program normally just takes a list of filenames you want to update, but
to avoid trivial mistakes, it refuses to add new entries to the index
$ git update-index --add hello example
------------------------------------------------
-and you have now told git to track those two files.
+and you have now told Git to track those two files.
In fact, as you did that, if you now look into your object directory,
-you'll notice that git will have added two new objects to the object
+you'll notice that Git will have added two new objects to the object
database. If you did exactly the steps above, you should now be able to do
----------------
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 (i.e., 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
----------------
look at the objects themselves, and typing long 40-character hex
names is not something you'd normally want to do. The above digression
was just to show that 'git update-index' did something magical, and
-actually saved away the contents of your files into the git object
+actually saved away the contents of your files into the Git object
database.
Updating the index did something else too: it created a `.git/index`
file. This is the index that describes your current working tree, and
something you should be very aware of. Again, you normally never worry
about the index file itself, but you should be aware of the fact that
-you have not actually really "checked in" your files into git so far,
-you've only *told* git about them.
+you have not actually really "checked in" your files into Git so far,
+you've only *told* Git about them.
-However, since git knows about them, you can now start using some of the
-most basic git commands to manipulate the files or look at their status.
+However, since Git knows about them, you can now start using some of the
+most basic Git commands to manipulate the files or look at their status.
-In particular, let's not even check in the two files into git yet, we'll
+In particular, let's not even check in the two files into Git yet, we'll
start off by adding another line to `hello` first:
------------------------------------------------
$ echo "It's a new day for git" >>hello
------------------------------------------------
-and you can now, since you told git about the previous state of `hello`, ask
-git what has changed in the tree compared to your old index, using the
+and you can now, since you told Git about the previous state of `hello`, ask
+Git what has changed in the tree compared to your old index, using the
'git diff-files' command:
------------
------------
-Committing git state
+Committing Git state
--------------------
-Now, we want to go to the next stage in git, which is to take the files
-that git knows about in the index, and commit them as a real tree. We do
+Now, we want to go to the next stage in Git, which is to take the files
+that Git knows about in the index, and commit them as a real tree. We do
that in two phases: creating a 'tree' object, and committing that 'tree'
object as a 'commit' object together with an explanation of what the
tree was all about, along with information of how we came to that state.
current index state, and write an object that describes that whole
index. In other words, we're now tying together all the different
filenames with their contents (and their permissions), and we're
-creating the equivalent of a git "directory" object:
+creating the equivalent of a Git "directory" object:
------------------------------------------------
$ git write-tree
flag really only determines whether the file *contents* to be compared
come from the working tree or not.
-This is not hard to understand, as soon as you realize that git simply
+This is not hard to understand, as soon as you realize that Git simply
never knows (or cares) about files that it is not told about
-explicitly. git will never go *looking* for files to compare, it
+explicitly. Git will never go *looking* for files to compare, it
expects you to tell it what the files are, and that's what the index
is there for.
================
$ git update-index hello
------------------------------------------------
-(note how we didn't need the `--add` flag this time, since git knew
+(note how we didn't need the `--add` flag this time, since Git knew
about the file already).
Note what happens to the different 'git diff-{asterisk}' versions here.
can just leave an empty message. Otherwise `git commit` will commit
the change for you.
-You've now made your first real git commit. And if you're interested in
+You've now made your first real Git commit. And if you're interested in
looking at what `git commit` really does, feel free to investigate:
it's a few very simple shell scripts to generate the helpful (?) commit
message headers, and a few one-liners that actually do the
In fact, together with the 'git rev-list' program (which generates a
list of revisions), 'git diff-tree' ends up being a veritable fount of
changes. A trivial (but very useful) script called 'git whatchanged' is
-included with git which does exactly this, and shows a log of recent
+included with Git which does exactly this, and shows a log of recent
activities.
To see the whole history of our pitiful little git-tutorial project, you
can still show it for each command just adding the `--root` option,
which is a flag for 'git diff-tree' accepted by both commands.
-With that, you should now be having some inkling of what git does, and
+With that, you should now be having some inkling of what Git does, and
can explore on your own.
[NOTE]
Most likely, you are not directly using the core
-git Plumbing commands, but using Porcelain such as 'git add', `git-rm'
+Git Plumbing commands, but using Porcelain such as 'git add', `git-rm'
and `git-commit'.
Tagging a version
-----------------
-In git, there are two kinds of tags, a "light" one, and an "annotated tag".
+In Git, there are two kinds of tags, a "light" one, and an "annotated tag".
A "light" tag is technically nothing more than a branch, except we put
it in the `.git/refs/tags/` subdirectory instead of calling it a `head`.
stuff, you can use your tag as an "anchor-point" to see what has changed
since you tagged it.
-An "annotated tag" is actually a real git object, and contains not only a
+An "annotated tag" is actually a real Git object, and contains not only a
pointer to the state you want to tag, but also a small tag name and
message, along with optionally a PGP signature that says that yes,
you really did
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`
+"repository" and "working tree". A Git repository normally *is* the
+working tree, with the local Git information hidden in the `.git`
subdirectory. There is nothing else. What you see is what you got.
[NOTE]
-You can tell git to split the git internal information from
+You can tell Git to split the Git internal information from
the directory that it tracks, but we'll ignore that for now: it's not
how normal projects work, and it's really only meant for special uses.
-So the mental model of "the git information is always tied directly to
+So the mental model of "the Git information is always tied directly to
the working tree that it describes" may not be technically 100%
accurate, but it's a good model for all normal use.
and it will be gone. There's no external repository, and there's no
history outside the project you created.
- - if you want to move or duplicate a git repository, you can do so. There
+ - if you want to move or duplicate a Git repository, you can do so. There
is 'git clone' command, but if all you want to do is just to
create a copy of your repository (with all the full history that
went along with it), you can do so with a regular
`cp -a git-tutorial new-git-tutorial`.
+
-Note that when you've moved or copied a git repository, your git index
+Note that when you've moved or copied a Git repository, your Git index
file (which caches various information, notably some of the "stat"
information for the files involved) will likely need to be refreshed.
So after you do a `cp -a` to create a new copy, you'll want to do
in the new repository to make sure that the index file is up-to-date.
Note that the second point is true even across machines. You can
-duplicate a remote git repository with *any* regular copy mechanism, be it
+duplicate a remote Git repository with *any* regular copy mechanism, be it
'scp', 'rsync' or 'wget'.
When copying a remote repository, you'll want to at a minimum update the
$ git reset
----------------
-and in fact a lot of the common git command combinations can be scripted
+and in fact a lot of the common Git command combinations can be scripted
with the `git xyz` interfaces. You can learn things by just looking
at what the various git scripts do. For example, `git reset` used to be
the above two lines implemented in 'git reset', but some things like
'git status' and 'git commit' are slightly more complex scripts around
-the basic git commands.
+the basic Git commands.
Many (most?) public remote repositories will not contain any of
the checked out files or even an index file, and will *only* contain the
-actual core git files. Such a repository usually doesn't even have the
-`.git` subdirectory, but has all the git files directly in the
+actual core Git files. Such a repository usually doesn't even have the
+`.git` subdirectory, but has all the Git files directly in the
repository.
-To create your own local live copy of such a "raw" git repository, you'd
+To create your own local live copy of such a "raw" Git repository, you'd
first create your own subdirectory for the project, and then copy the
raw repository contents into the `.git` directory. For example, to
-create your own copy of the git repository, you'd do the following
+create your own copy of the Git repository, you'd do the following
----------------
$ mkdir my-git
----------------
to populate the index. However, now you have populated the index, and
-you have all the git internal files, but you will notice that you don't
+you have all the Git internal files, but you will notice that you don't
actually have any of the working tree files to work on. To get
those, you'd check them out with
Creating a new branch
---------------------
-Branches in git are really nothing more than pointers into the git
+Branches in Git are really nothing more than pointers into the Git
object database from within the `.git/refs/` subdirectory, and as we
already discussed, the `HEAD` branch is nothing but a symlink to one of
these object pointers.
You can at any time create a new branch by just picking an arbitrary
-point in the project history, and just writing the SHA1 name of that
+point in the project history, and just writing the SHA-1 name of that
object into a file under `.git/refs/heads/`. You can use any filename you
want (and indeed, subdirectories), but the convention is that the
"normal" branch is called `master`. That's just a convention, though,
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`, with an `-i` flag (it tells
-git to 'include' that file in addition to what you have done to
+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.
the merge can be resolved automatically.
Now, in this case we've intentionally created a situation where the
-merge will need to be fixed up by hand, though, so git will do as much
+merge will need to be fixed up by hand, though, so Git will do as much
of it as it can automatically (which in this case is just merge the `example`
file, which had no differences in the `mybranch` branch), and say:
history looks like. Notice that `mybranch` still exists, and you can
switch to it, and continue to work with it if you want to. The
`mybranch` branch will not contain the merge, but next time you merge it
-from the `master` branch, git will know how you merged it, so you'll not
+from the `master` branch, Git will know how you merged it, so you'll not
have to do _that_ merge again.
Another useful tool, especially if you do not always work in X-Window
---------------------
It's usually much more common that you merge with somebody else than
-merging with your own branches, so it's worth pointing out that git
+merging with your own branches, so it's worth pointing out that Git
makes that very easy too, and in fact, it's not that different from
doing a 'git merge'. In fact, a remote merge ends up being nothing
more than "fetch the work from a remote repository into a temporary tag"
remote machine. It finds out the set of objects the other side
lacks by exchanging the head commits both ends have and
transfers (close to) minimum set of objects. It is by far the
-most efficient way to exchange git objects between repositories.
+most efficient way to exchange Git objects between repositories.
Local directory::
`/path/to/repo.git/`
both ends on the local machine instead of running other end on
the remote machine via 'ssh'.
-git Native::
+Git Native::
`git://remote.machine/path/to/repo.git/`
+
This transport was designed for anonymous downloading. Like SSH
sometimes also called 'commit walkers'.
+
The 'commit walkers' are sometimes also called 'dumb
-transports', because they do not require any git aware smart
-server like git Native transport does. Any stock HTTP server
+transports', because they do not require any Git aware smart
+server like Git Native transport does. Any stock HTTP server
that does not even support directory index would suffice. But
you must prepare your repository with 'git update-server-info'
to help dumb transport downloaders.
etc.). After reading three trees into three stages, the paths
that are the same in all three stages are 'collapsed' into stage
0. Also paths that are the same in two of three stages are
-collapsed into stage 0, taking the SHA1 from either stage 2 or
+collapsed into stage 0, taking the SHA-1 from either stage 2 or
stage 3, whichever is different from stage 1 (i.e. only one side
changed from the common ancestor).
[NOTE]
This public repository could further be mirrored, and that is
-how git repositories at `kernel.org` are managed.
+how Git repositories at `kernel.org` are managed.
Publishing the changes from your local (private) repository to
your remote (public) repository requires a write privilege on
on the remote machine. The communication between the two over
the network internally uses an SSH connection.
-Your private repository's git directory is usually `.git`, but
+Your private repository's Git directory is usually `.git`, but
your public repository is often named after the project name,
i.e. `<project>.git`. Let's create such a public repository for
project `my-git`. After logging into the remote machine, create
$ mkdir my-git.git
------------
-Then, make that directory into a git repository by running
+Then, make that directory into a Git repository by running
'git init', but this time, since its name is not the usual
`.git`, we do things slightly differently:
branch head (i.e. `master` in this case) and objects reachable
from them in your current repository.
-As a real example, this is how I update my public git
+As a real example, this is how I update my public Git
repository. Kernel.org mirror network takes care of the
propagation to other publicly visible machines:
-----------------------
Earlier, we saw that one file under `.git/objects/??/` directory
-is stored for each git object you create. This representation
+is stored for each Git object you create. This representation
is efficient to create atomically and safely, but
-not so convenient to transport over the network. Since git objects are
+not so convenient to transport over the network. Since Git objects are
immutable once they are created, there is a way to optimize the
storage by "packing them together". The command
Working with Others
-------------------
-Although git is a truly distributed system, it is often
+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
link:http://www.xenotime.net/linux/mentor/linux-mentoring-2006.pdf[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
+There is nothing fundamental in Git that enforces the "chain of
patch flow" this hierarchy implies. You do not have to pull
from only one remote repository.
If you are coming from CVS background, the style of cooperation
suggested in the previous section may be new to you. You do not
-have to worry. git supports "shared public repository" style of
+have to worry. Git supports "shared public repository" style of
cooperation you are probably more familiar with as well.
See linkgit:gitcvs-migration[7] for the details.
It is likely that you will be working on more than one thing at
a time. It is easy to manage those more-or-less independent tasks
-using branches with git.
+using branches with Git.
We have already seen how branches work previously,
with "fun and work" example using two branches. The idea is the