gitcore-tutorial(7)
===================

NAME
----
gitcore-tutorial - A Git core tutorial for developers

SYNOPSIS
--------
git *

DESCRIPTION
-----------

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].

However, an understanding of these low-level tools can be helpful if
you want to understand Git's internals.

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 when the porcelain isn't flushing.

Back when this document was originally written, many porcelain
commands were shell scripts. For simplicity, it still uses them as
examples to illustrate how plumbing is fit together to form the
porcelain commands. The source tree includes some of these scripts in
contrib/examples/ for reference. Although these are not implemented as
shell scripts anymore, the description of what the plumbing layer
commands do is still valid.

[NOTE]
Deeper technical details are often marked as Notes, which you can
skip on your first reading.


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':

------------------------------------------------
$ mkdir git-tutorial
$ cd git-tutorial
$ git init
------------------------------------------------

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
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 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
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 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.

However, this is only a convention, and you can name your branches
anything you want, and don't have to