A short git tutorial
====================
v0.99.5, Aug 2005
Introduction
------------
This is trying to be a short tutorial on setting up and using a git
repository, mainly because being hands-on and using explicit examples is
often the best way of explaining what is going on.
In normal life, most people wouldn't use the "core" git programs
directly, but rather script around them to make them more palatable.
Understanding the core git stuff may help some people get those scripts
done, though, and it may also be instructive in helping people
understand what it is that the higher-level helper scripts are actually
doing.
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...
Creating a git repository
-------------------------
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.
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`:
------------------------------------------------
mkdir git-tutorial
cd git-tutorial
git-init-db
------------------------------------------------
to which git will reply
defaulting to local storage area
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
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")
+
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
start your `HEAD` development branch yet.
- a subdirectory called `objects`, which will contain all the
objects of your project. You should never have any real reason to
look at the objects directly, but you might want to know that these
objects are what contains all the real 'data' in your repository.
- a subdirectory called `refs`, which contains references to objects.
In particular, the `refs` subdirectory will contain two other
subdirectories, named `heads` and `tags` respectively. They do
exactly what their names imply: they contain references to any number
of different 'heads' of development (aka 'branches'), and to any
'tags' that you have created to name specific versions in your
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
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.
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
valid, though.
[NOTE]
An 'object' is identified by its 160-bit SHA1 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`
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
references in these `refs` subdirectories when you actually start
populating your tree.
[NOTE]
An advanced user may want to take a look at the
link:repository-layout.html[repository layout] document
after finishing this tutorial.
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
---------------------------
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
|