gitcore-tutorial.txt 60.8 KB
Newer Older
1 2
gitcore-tutorial(7)
===================
J. Bruce Fields's avatar
J. Bruce Fields committed
3

4 5
NAME
----
6
gitcore-tutorial - A Git core tutorial for developers
7 8 9 10 11 12 13

SYNOPSIS
--------
git *

DESCRIPTION
-----------
J. Bruce Fields's avatar
J. Bruce Fields committed
14

15 16
This tutorial explains how to use the "core" Git commands to set up and
work with a Git repository.
J. Bruce Fields's avatar
J. Bruce Fields committed
17

18
If you just need to use Git as a revision control system you may prefer
19 20
to start with "A Tutorial Introduction to Git" (linkgit:gittutorial[7]) or
link:user-manual.html[the Git User Manual].
21 22

However, an understanding of these low-level tools can be helpful if
23
you want to understand Git's internals.
J. Bruce Fields's avatar
J. Bruce Fields committed
24

25
The core Git is often called "plumbing", with the prettier user
J. Bruce Fields's avatar
J. Bruce Fields committed
26 27
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
28
plumbing does when the porcelain isn't flushing.
J. Bruce Fields's avatar
J. Bruce Fields committed
29

30 31 32 33 34 35 36 37
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.

J. Bruce Fields's avatar
J. Bruce Fields committed
38
[NOTE]
39 40
Deeper technical details are often marked as Notes, which you can
skip on your first reading.
J. Bruce Fields's avatar
J. Bruce Fields committed
41 42


43
Creating a Git repository
J. Bruce Fields's avatar
J. Bruce Fields committed
44 45
-------------------------

46
Creating a new Git repository couldn't be easier: all Git repositories start
J. Bruce Fields's avatar
J. Bruce Fields committed
47 48 49
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
50
to import into Git.
J. Bruce Fields's avatar
J. Bruce Fields committed
51 52

For our first example, we're going to start a totally new repository from
53
scratch, with no pre-existing files, and we'll call it 'git-tutorial'.
J. Bruce Fields's avatar
J. Bruce Fields committed
54
To start up, create a subdirectory for it, change into that
55
subdirectory, and initialize the Git infrastructure with 'git init':
J. Bruce Fields's avatar
J. Bruce Fields committed
56 57 58 59

------------------------------------------------
$ mkdir git-tutorial
$ cd git-tutorial
60
$ git init
J. Bruce Fields's avatar
J. Bruce Fields committed
61 62
------------------------------------------------

63
to which Git will reply
J. Bruce Fields's avatar
J. Bruce Fields committed
64 65

----------------
66
Initialized empty Git repository in .git/
J. Bruce Fields's avatar
J. Bruce Fields committed
67 68
----------------

69
which is just Git's way of saying that you haven't been doing anything
J. Bruce Fields's avatar
J. Bruce Fields committed
70 71
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
72
inspect that with 'ls'. For your new empty project, it should show you
J. Bruce Fields's avatar
J. Bruce Fields committed
73 74
three entries, among other things:

75 76 77
 - 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.
J. Bruce Fields's avatar
J. Bruce Fields committed
78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97
+
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
98
why the `.git/HEAD` file was created points to it even if it
J. Bruce Fields's avatar
J. Bruce Fields committed
99 100 101 102 103 104
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`
105
branch. A number of the Git tools will assume that `.git/HEAD` is
J. Bruce Fields's avatar
J. Bruce Fields committed
106 107 108
valid, though.

[NOTE]
109
An 'object' is identified by its 160-bit SHA-1 hash, aka 'object name',
J. Bruce Fields's avatar
J. Bruce Fields committed
110
and a reference to an object is always the 40-byte hex
111
representation of that SHA-1 name. The files in the `refs`
J. Bruce Fields's avatar
J. Bruce Fields committed
112
subdirectory are expected to contain these hex references
113
(usually with a final `\n` at the end), and you should thus
J. Bruce Fields's avatar
J. Bruce Fields committed
114 115 116 117 118
expect to see a number of 41-byte files containing these
references in these `refs` subdirectories when you actually start
populating your tree.

[NOTE]
119
An advanced user may want to take a look at linkgit:gitrepository-layout[5]
J. Bruce Fields's avatar
J. Bruce Fields committed
120 121
after finishing this tutorial.

122
You have now created your first Git repository. Of course, since it's
J. Bruce Fields's avatar
J. Bruce Fields committed
123 124 125
empty, that's not very useful, so let's start populating it with data.


126
Populating a Git repository
J. Bruce Fields's avatar
J. Bruce Fields committed
127 128 129 130 131 132
---------------------------

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
133
in your Git repository. We'll start off with a few bad examples, just to
J. Bruce Fields's avatar
J. Bruce Fields committed
134 135 136 137 138 139 140
get a feel for how this works:

------------------------------------------------
$ echo "Hello World" >hello
$ echo "Silly example" >example
------------------------------------------------

141 142
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:
J. Bruce Fields's avatar
J. Bruce Fields committed
143 144 145 146 147 148

 - fill in the 'index' file (aka 'cache') with the information about your
   working tree state.

 - commit that index file as an object.

149
The first step is trivial: when you want to tell Git about any changes
150
to your working tree, you use the 'git update-index' program. That
J. Bruce Fields's avatar
J. Bruce Fields committed
151 152 153
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
(or remove existing ones) unless you explicitly tell it that you're
154 155
adding a new entry with the `--add` flag (or removing an entry with the
`--remove`) flag.
J. Bruce Fields's avatar
J. Bruce Fields committed
156 157 158 159

So to populate the index with the two files you just created, you can do

------------------------------------------------
160
$ git update-index --add hello example
J. Bruce Fields's avatar
J. Bruce Fields committed
161 162
------------------------------------------------

163
and you have now told Git to track those two files.
J. Bruce Fields's avatar
J. Bruce Fields committed
164 165

In fact, as you did that, if you now look into your object directory,
166
you'll notice that Git will have added two new objects to the object
J. Bruce Fields's avatar
J. Bruce Fields committed
167 168 169 170 171 172 173 174 175 176
database. If you did exactly the steps above, you should now be able to do


----------------
$ ls .git/objects/??/*
----------------

and see two files:

----------------
Junio C Hamano's avatar
Junio C Hamano committed
177
.git/objects/55/7db03de997c86a4a028e1ebd3a1ceb225be238
J. Bruce Fields's avatar
J. Bruce Fields committed
178 179 180
.git/objects/f2/4c74a2e500f5ee1332c86b94199f52b1d1d962
----------------

181 182
which correspond with the objects with names of `557db...` and
`f24c7...` respectively.
J. Bruce Fields's avatar
J. Bruce Fields committed
183

184
If you want to, you can use 'git cat-file' to look at those objects, but
J. Bruce Fields's avatar
J. Bruce Fields committed
185 186 187
you'll have to use the object name, not the filename of the object:

----------------
188
$ git cat-file -t 557db03de997c86a4a028e1ebd3a1ceb225be238
J. Bruce Fields's avatar
J. Bruce Fields committed
189 190
----------------

191
where the `-t` tells 'git cat-file' to tell you what the "type" of the
192
object is. Git will tell you that you have a "blob" object (i.e., just a
J. Bruce Fields's avatar
J. Bruce Fields committed
193 194 195
regular file), and you can see the contents with

----------------
196
$ git cat-file blob 557db03
J. Bruce Fields's avatar
J. Bruce Fields committed
197 198
----------------

199
which will print out "Hello World". The object `557db03` is nothing
J. Bruce Fields's avatar
J. Bruce Fields committed
200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215
more than the contents of your file `hello`.

[NOTE]
Don't confuse that object with the file `hello` itself. The
object is literally just those specific *contents* of the file, and
however much you later change the contents in file `hello`, the object
we just looked at will never change. Objects are immutable.

[NOTE]
The second example demonstrates that you can
abbreviate the object name to only the first several
hexadecimal digits in most places.

Anyway, as we mentioned previously, you normally never actually take a
look at the objects themselves, and typing long 40-character hex
names is not something you'd normally want to do. The above digression
216
was just to show that 'git update-index' did something magical, and
217
actually saved away the contents of your files into the Git object
J. Bruce Fields's avatar
J. Bruce Fields committed
218 219 220 221 222 223
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
224 225
you have not actually really "checked in" your files into Git so far,
you've only *told* Git about them.
J. Bruce Fields's avatar
J. Bruce Fields committed
226

227 228
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.
J. Bruce Fields's avatar
J. Bruce Fields committed
229

230
In particular, let's not even check in the two files into Git yet, we'll
J. Bruce Fields's avatar
J. Bruce Fields committed
231 232 233 234 235 236
start off by adding another line to `hello` first:

------------------------------------------------
$ echo "It's a new day for git" >>hello
------------------------------------------------

237 238
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
239
'git diff-files' command:
J. Bruce Fields's avatar
J. Bruce Fields committed
240 241

------------
242
$ git diff-files
J. Bruce Fields's avatar
J. Bruce Fields committed
243 244 245
------------

Oops. That wasn't very readable. It just spit out its own internal
246
version of a 'diff', but that internal version really just tells you
J. Bruce Fields's avatar
J. Bruce Fields committed
247 248 249
that it has noticed that "hello" has been modified, and that the old object
contents it had have been replaced with something else.

250
To make it readable, we can tell 'git diff-files' to output the
J. Bruce Fields's avatar
J. Bruce Fields committed
251 252 253
differences as a patch, using the `-p` flag:

------------
254
$ git diff-files -p
J. Bruce Fields's avatar
J. Bruce Fields committed
255 256 257 258 259 260 261
diff --git a/hello b/hello
index 557db03..263414f 100644
--- a/hello
+++ b/hello
@@ -1 +1,2 @@
 Hello World
+It's a new day for git
262
------------
J. Bruce Fields's avatar
J. Bruce Fields committed
263 264 265

i.e. the diff of the change we caused by adding another line to `hello`.

266
In other words, 'git diff-files' always shows us the difference between
J. Bruce Fields's avatar
J. Bruce Fields committed
267 268 269
what is recorded in the index, and what is currently in the working
tree. That's very useful.

270
A common shorthand for `git diff-files -p` is to just write `git
J. Bruce Fields's avatar
J. Bruce Fields committed
271 272 273 274 275 276 277 278 279 280 281 282 283 284
diff`, which will do the same thing.

------------
$ git diff
diff --git a/hello b/hello
index 557db03..263414f 100644
--- a/hello
+++ b/hello
@@ -1 +1,2 @@
 Hello World
+It's a new day for git
------------


285
Committing Git state
J. Bruce Fields's avatar
J. Bruce Fields committed
286 287
--------------------

288 289
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
J. Bruce Fields's avatar
J. Bruce Fields committed
290 291 292 293
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.

294
Creating a tree object is trivial, and is done with 'git write-tree'.
295
There are no options or other input: `git write-tree` will take the
J. Bruce Fields's avatar
J. Bruce Fields committed
296 297 298
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
299
creating the equivalent of a Git "directory" object:
J. Bruce Fields's avatar
J. Bruce Fields committed
300 301

------------------------------------------------
302
$ git write-tree
J. Bruce Fields's avatar
J. Bruce Fields committed
303 304 305 306 307 308 309 310 311 312
------------------------------------------------

and this will just output the name of the resulting tree, in this case
(if you have done exactly as I've described) it should be

----------------
8988da15d077d4829fc51d8544c097def6644dbb
----------------

which is another incomprehensible object name. Again, if you want to,
313
you can use `git cat-file -t 8988d...` to see that this time the object
J. Bruce Fields's avatar
J. Bruce Fields committed
314
is not a "blob" object, but a "tree" object (you can also use
315
`git cat-file` to actually output the raw object contents, but you'll see
J. Bruce Fields's avatar
J. Bruce Fields committed
316 317
mainly a binary mess, so that's less interesting).

318
However -- normally you'd never use 'git write-tree' on its own, because
J. Bruce Fields's avatar
J. Bruce Fields committed
319
normally you always commit a tree into a commit object using the
320 321 322
'git commit-tree' command. In fact, it's easier to not actually use
'git write-tree' on its own at all, but to just pass its result in as an
argument to 'git commit-tree'.
J. Bruce Fields's avatar
J. Bruce Fields committed
323

324
'git commit-tree' normally takes several arguments -- it wants to know
J. Bruce Fields's avatar
J. Bruce Fields committed
325 326
what the 'parent' of a commit was, but since this is the first commit
ever in this new repository, and it has no parents, we only need to pass in
327
the object name of the tree. However, 'git commit-tree' also wants to get a
328 329
commit message on its standard input, and it will write out the resulting
object name for the commit to its standard output.
J. Bruce Fields's avatar
J. Bruce Fields committed
330 331 332 333

And this is where we create the `.git/refs/heads/master` file
which is pointed at by `HEAD`. This file is supposed to contain
the reference to the top-of-tree of the master branch, and since
334
that's exactly what 'git commit-tree' spits out, we can do this
J. Bruce Fields's avatar
J. Bruce Fields committed
335 336 337
all with a sequence of simple shell commands:

------------------------------------------------
338 339 340
$ tree=$(git write-tree)
$ commit=$(echo 'Initial commit' | git commit-tree $tree)
$ git update-ref HEAD $commit
J. Bruce Fields's avatar
J. Bruce Fields committed
341 342
------------------------------------------------

343 344 345
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.
J. Bruce Fields's avatar
J. Bruce Fields committed
346 347 348 349 350 351 352 353 354 355

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
you could have just written `git commit`
instead, and it would have done the above magic scripting for you.


Making a change
---------------

356
Remember how we did the 'git update-index' on file `hello` and then we
J. Bruce Fields's avatar
J. Bruce Fields committed
357
changed `hello` afterward, and could compare the new state of `hello` with the
Junio C Hamano's avatar
Junio C Hamano committed
358
state we saved in the index file?
J. Bruce Fields's avatar
J. Bruce Fields committed
359

360
Further, remember how I said that 'git write-tree' writes the contents
J. Bruce Fields's avatar
J. Bruce Fields committed
361 362 363 364 365 366
of the *index* file to the tree, and thus what we just committed was in
fact the *original* contents of the file `hello`, not the new ones. We did
that on purpose, to show the difference between the index state, and the
state in the working tree, and how they don't have to match, even
when we commit things.

367
As before, if we do `git diff-files -p` in our git-tutorial project,
J. Bruce Fields's avatar
J. Bruce Fields committed
368 369 370
we'll still see the same difference we saw last time: the index file
hasn't changed by the act of committing anything. However, now that we
have committed something, we can also learn to use a new command:
371
'git diff-index'.
J. Bruce Fields's avatar
J. Bruce Fields committed
372

373 374
Unlike 'git diff-files', which showed the difference between the index
file and the working tree, 'git diff-index' shows the differences
J. Bruce Fields's avatar
J. Bruce Fields committed
375
between a committed *tree* and either the index file or the working
376
tree. In other words, 'git diff-index' wants a tree to be diffed
J. Bruce Fields's avatar
J. Bruce Fields committed
377
against, and before we did the commit, we couldn't do that, because we
Junio C Hamano's avatar
Junio C Hamano committed
378
didn't have anything to diff against.
J. Bruce Fields's avatar
J. Bruce Fields committed
379 380 381 382

But now we can do

----------------
383
$ git diff-index -p HEAD
J. Bruce Fields's avatar
J. Bruce Fields committed
384 385
----------------

386
(where `-p` has the same meaning as it did in 'git diff-files'), and it
Junio C Hamano's avatar
Junio C Hamano committed
387
will show us the same difference, but for a totally different reason.
J. Bruce Fields's avatar
J. Bruce Fields committed
388 389 390 391 392 393 394 395 396 397 398 399 400
Now we're comparing the working tree not against the index file,
but against the tree we just wrote. It just so happens that those two
are obviously the same, so we get the same result.

Again, because this is a common operation, you can also just shorthand
it with

----------------
$ git diff HEAD
----------------

which ends up doing the above for you.

401
In other words, 'git diff-index' normally compares a tree against the
402
working tree, but when given the `--cached` flag, it is told to
J. Bruce Fields's avatar
J. Bruce Fields committed
403 404
instead compare against just the index cache contents, and ignore the
current working tree state entirely. Since we just wrote the index
405
file to HEAD, doing `git diff-index --cached -p HEAD` should thus return
Junio C Hamano's avatar
Junio C Hamano committed
406
an empty set of differences, and that's exactly what it does.
J. Bruce Fields's avatar
J. Bruce Fields committed
407 408 409

[NOTE]
================
410
'git diff-index' really always uses the index for its
J. Bruce Fields's avatar
J. Bruce Fields committed
411 412 413
comparisons, and saying that it compares a tree against the working
tree is thus not strictly accurate. In particular, the list of
files to compare (the "meta-data") *always* comes from the index file,
414
regardless of whether the `--cached` flag is used or not. The `--cached`
J. Bruce Fields's avatar
J. Bruce Fields committed
415 416 417
flag really only determines whether the file *contents* to be compared
come from the working tree or not.

418
This is not hard to understand, as soon as you realize that Git simply
J. Bruce Fields's avatar
J. Bruce Fields committed
419
never knows (or cares) about files that it is not told about
420
explicitly. Git will never go *looking* for files to compare, it
J. Bruce Fields's avatar
J. Bruce Fields committed
421 422 423 424 425 426 427 428 429 430 431 432
expects you to tell it what the files are, and that's what the index
is there for.
================

However, our next step is to commit the *change* we did, and again, to
understand what's going on, keep in mind the difference between "working
tree contents", "index file" and "committed tree". We have changes
in the working tree that we want to commit, and we always have to
work through the index file, so the first thing we need to do is to
update the index cache:

------------------------------------------------
433
$ git update-index hello
J. Bruce Fields's avatar
J. Bruce Fields committed
434 435
------------------------------------------------

436
(note how we didn't need the `--add` flag this time, since Git knew
J. Bruce Fields's avatar
J. Bruce Fields committed
437 438
about the file already).

439 440
Note what happens to the different 'git diff-{asterisk}' versions here.
After we've updated `hello` in the index, `git diff-files -p` now shows no
441
differences, but `git diff-index -p HEAD` still *does* show that the
J. Bruce Fields's avatar
J. Bruce Fields committed
442
current state is different from the state we committed. In fact, now
443
'git diff-index' shows the same difference whether we use the `--cached`
J. Bruce Fields's avatar
J. Bruce Fields committed
444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466
flag or not, since now the index is coherent with the working tree.

Now, since we've updated `hello` in the index, we can commit the new
version. We could do it by writing the tree by hand again, and
committing the tree (this time we'd have to use the `-p HEAD` flag to
tell commit that the HEAD was the *parent* of the new commit, and that
this wasn't an initial commit any more), but you've done that once
already, so let's just use the helpful script this time:

------------------------------------------------
$ git commit
------------------------------------------------

which starts an editor for you to write the commit message and tells you
a bit about what you have done.

Write whatever message you want, and all the lines that start with '#'
will be pruned out, and the rest will be used as the commit message for
the change. If you decide you don't want to commit anything after all at
this point (you can continue to edit things and update the index), you
can just leave an empty message. Otherwise `git commit` will commit
the change for you.

467
You've now made your first real Git commit. And if you're interested in
J. Bruce Fields's avatar
J. Bruce Fields committed
468 469 470
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
471
commit itself ('git commit').
J. Bruce Fields's avatar
J. Bruce Fields committed
472 473 474 475 476 477 478


Inspecting Changes
------------------

While creating changes is useful, it's even more useful if you can tell
later what changed. The most useful command for this is another of the
479
'diff' family, namely 'git diff-tree'.
J. Bruce Fields's avatar
J. Bruce Fields committed
480

481
'git diff-tree' can be given two arbitrary trees, and it will tell you the
J. Bruce Fields's avatar
J. Bruce Fields committed
482 483 484 485 486 487
differences between them. Perhaps even more commonly, though, you can
give it just a single commit object, and it will figure out the parent
of that commit itself, and show the difference directly. Thus, to get
the same diff that we've already seen several times, we can now do

----------------
488
$ git diff-tree -p HEAD
J. Bruce Fields's avatar
J. Bruce Fields committed
489 490 491 492 493 494 495 496
----------------

(again, `-p` means to show the difference as a human-readable patch),
and it will show what the last commit (in `HEAD`) actually changed.

[NOTE]
============
Here is an ASCII art by Jon Loeliger that illustrates how
497
various 'diff-{asterisk}' commands compare things.
J. Bruce Fields's avatar
J. Bruce Fields committed
498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528

                      diff-tree
                       +----+
                       |    |
                       |    |
                       V    V
                    +-----------+
                    | Object DB |
                    |  Backing  |
                    |   Store   |
                    +-----------+
                      ^    ^
                      |    |
                      |    |  diff-index --cached
                      |    |
          diff-index  |    V
                      |  +-----------+
                      |  |   Index   |
                      |  |  "cache"  |
                      |  +-----------+
                      |    ^
                      |    |
                      |    |  diff-files
                      |    |
                      V    V
                    +-----------+
                    |  Working  |
                    | Directory |
                    +-----------+
============

529
More interestingly, you can also give 'git diff-tree' the `--pretty` flag,
530
which tells it to also show the commit message and author and date of the
J. Bruce Fields's avatar
J. Bruce Fields committed
531 532 533 534
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.

535 536
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
537 538 539
changes.  You can emulate `git log`, `git log -p`, etc. with a trivial
script that pipes the output of `git rev-list` to `git diff-tree --stdin`,
which was exactly how early versions of `git log` were implemented.
J. Bruce Fields's avatar
J. Bruce Fields committed
540 541 542 543 544


Tagging a version
-----------------

545
In Git, there are two kinds of tags, a "light" one, and an "annotated tag".
J. Bruce Fields's avatar
J. Bruce Fields committed
546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562

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`.
So the simplest form of tag involves nothing more than

------------------------------------------------
$ git tag my-first-tag
------------------------------------------------

which just writes the current `HEAD` into the `.git/refs/tags/my-first-tag`
file, after which point you can then use this symbolic name for that
particular state. You can, for example, do

----------------
$ git diff my-first-tag
----------------

Thomas Zander's avatar
Thomas Zander committed
563
to diff your current state against that tag which at this point will
J. Bruce Fields's avatar
J. Bruce Fields committed
564 565 566 567
obviously be an empty diff, but if you continue to develop and commit
stuff, you can use your tag as an "anchor-point" to see what has changed
since you tagged it.

568
An "annotated tag" is actually a real Git object, and contains not only a
J. Bruce Fields's avatar
J. Bruce Fields committed
569 570 571 572
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
that tag. You create these annotated tags with either the `-a` or
573
`-s` flag to 'git tag':
J. Bruce Fields's avatar
J. Bruce Fields committed
574 575 576 577 578 579

----------------
$ git tag -s <tagname>
----------------

which will sign the current `HEAD` (but you can also give it another
580
argument that specifies the thing to tag, e.g., you could have tagged the
J. Bruce Fields's avatar
J. Bruce Fields committed
581 582 583 584 585 586 587 588 589 590 591 592
current `mybranch` point by using `git tag <tagname> mybranch`).

You normally only do signed tags for major releases or things
like that, while the light-weight tags are useful for any marking you
want to do -- any time you decide that you want to remember a certain
point, just create a private tag for it, and you have a nice symbolic
name for the state at that point.


Copying repositories
--------------------

593
Git repositories are normally totally self-sufficient and relocatable.
J. Bruce Fields's avatar
J. Bruce Fields committed
594
Unlike CVS, for example, there is no separate notion of
595 596
"repository" and "working tree". A Git repository normally *is* the
working tree, with the local Git information hidden in the `.git`
J. Bruce Fields's avatar
J. Bruce Fields committed
597 598 599
subdirectory. There is nothing else. What you see is what you got.

[NOTE]
600
You can tell Git to split the Git internal information from
J. Bruce Fields's avatar
J. Bruce Fields committed
601 602
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.
603
So the mental model of "the Git information is always tied directly to
J. Bruce Fields's avatar
J. Bruce Fields committed
604 605 606
the working tree that it describes" may not be technically 100%
accurate, but it's a good model for all normal use.

Junio C Hamano's avatar
Junio C Hamano committed
607
This has two implications:
J. Bruce Fields's avatar
J. Bruce Fields committed
608 609 610 611 612 613 614 615 616 617 618

 - if you grow bored with the tutorial repository you created (or you've
   made a mistake and want to start all over), you can just do simple
+
----------------
$ rm -rf git-tutorial
----------------
+
and it will be gone. There's no external repository, and there's no
history outside the project you created.

619
 - if you want to move or duplicate a Git repository, you can do so. There
620
   is 'git clone' command, but if all you want to do is just to
J. Bruce Fields's avatar
J. Bruce Fields committed
621 622 623 624
   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`.
+
625
Note that when you've moved or copied a Git repository, your Git index
J. Bruce Fields's avatar
J. Bruce Fields committed
626 627 628 629 630
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
+
----------------
631
$ git update-index --refresh
J. Bruce Fields's avatar
J. Bruce Fields committed
632 633 634 635 636
----------------
+
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
637
duplicate a remote Git repository with *any* regular copy mechanism, be it
638
'scp', 'rsync' or 'wget'.
J. Bruce Fields's avatar
J. Bruce Fields committed
639 640 641 642 643

When copying a remote repository, you'll want to at a minimum update the
index cache when you do this, and especially with other peoples'
repositories you often want to make sure that the index cache is in some
known state (you don't know *what* they've done and not yet checked in),
644
so usually you'll precede the 'git update-index' with a
J. Bruce Fields's avatar
J. Bruce Fields committed
645 646

----------------
647 648
$ git read-tree --reset HEAD
$ git update-index --refresh
J. Bruce Fields's avatar
J. Bruce Fields committed
649 650 651
----------------

which will force a total index re-build from the tree pointed to by `HEAD`.
652
It resets the index contents to `HEAD`, and then the 'git update-index'
J. Bruce Fields's avatar
J. Bruce Fields committed
653 654
makes sure to match up all index entries with the checked-out files.
If the original repository had uncommitted changes in its
655
working tree, `git update-index --refresh` notices them and
J. Bruce Fields's avatar
J. Bruce Fields committed
656 657 658 659 660 661 662 663
tells you they need to be updated.

The above can also be written as simply

----------------
$ git reset
----------------

664
and in fact a lot of the common Git command combinations can be scripted
J. Bruce Fields's avatar
J. Bruce Fields committed
665
with the `git xyz` interfaces.  You can learn things by just looking
666
at what the various git scripts do.  For example, `git reset` used to be
667 668
the above two lines implemented in 'git reset', but some things like
'git status' and 'git commit' are slightly more complex scripts around
669
the basic Git commands.
J. Bruce Fields's avatar
J. Bruce Fields committed
670 671 672

Many (most?) public remote repositories will not contain any of
the checked out files or even an index file, and will *only* contain the
673 674
actual core Git files. Such a repository usually doesn't even have the
`.git` subdirectory, but has all the Git files directly in the
Junio C Hamano's avatar
Junio C Hamano committed
675
repository.
J. Bruce Fields's avatar
J. Bruce Fields committed
676

677
To create your own local live copy of such a "raw" Git repository, you'd
J. Bruce Fields's avatar
J. Bruce Fields committed
678 679
first create your own subdirectory for the project, and then copy the
raw repository contents into the `.git` directory. For example, to
680
create your own copy of the Git repository, you'd do the following
J. Bruce Fields's avatar
J. Bruce Fields committed
681 682 683 684 685 686 687

----------------
$ mkdir my-git
$ cd my-git
$ rsync -rL rsync://rsync.kernel.org/pub/scm/git/git.git/ .git
----------------

Junio C Hamano's avatar
Junio C Hamano committed
688
followed by
J. Bruce Fields's avatar
J. Bruce Fields committed
689 690

----------------
691
$ git read-tree HEAD
J. Bruce Fields's avatar
J. Bruce Fields committed
692 693 694
----------------

to populate the index. However, now you have populated the index, and
695
you have all the Git internal files, but you will notice that you don't
J. Bruce Fields's avatar
J. Bruce Fields committed
696 697 698 699
actually have any of the working tree files to work on. To get
those, you'd check them out with

----------------
700
$ git checkout-index -u -a
J. Bruce Fields's avatar
J. Bruce Fields committed
701 702 703 704 705 706
----------------

where the `-u` flag means that you want the checkout to keep the index
up-to-date (so that you don't have to refresh it afterward), and the
`-a` flag means "check out all files" (if you have a stale copy or an
older version of a checked out tree you may also need to add the `-f`
707
flag first, to tell 'git checkout-index' to *force* overwriting of any old
Junio C Hamano's avatar
Junio C Hamano committed
708
files).
J. Bruce Fields's avatar
J. Bruce Fields committed
709 710 711 712

Again, this can all be simplified with

----------------
713
$ git clone git://git.kernel.org/pub/scm/git/git.git/ my-git
J. Bruce Fields's avatar
J. Bruce Fields committed
714 715 716 717 718 719 720
$ cd my-git
$ git checkout
----------------

which will end up doing all of the above for you.

You have now successfully copied somebody else's (mine) remote
Junio C Hamano's avatar
Junio C Hamano committed
721
repository, and checked it out.
J. Bruce Fields's avatar
J. Bruce Fields committed
722 723 724 725 726


Creating a new branch
---------------------

727
Branches in Git are really nothing more than pointers into the Git
J. Bruce Fields's avatar
J. Bruce Fields committed
728 729
object database from within the `.git/refs/` subdirectory, and as we
already discussed, the `HEAD` branch is nothing but a symlink to one of
Junio C Hamano's avatar
Junio C Hamano committed
730
these object pointers.
J. Bruce Fields's avatar
J. Bruce Fields committed
731 732

You can at any time create a new branch by just picking an arbitrary
733
point in the project history, and just writing the SHA-1 name of that
J. Bruce Fields's avatar
J. Bruce Fields committed
734 735 736
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,
Junio C Hamano's avatar
Junio C Hamano committed
737
and nothing enforces it.
J. Bruce Fields's avatar
J. Bruce Fields committed
738 739 740 741 742 743 744 745 746 747

To show that as an example, let's go back to the git-tutorial repository we
used earlier, and create a branch in it. You do that by simply just
saying that you want to check out a new branch:

------------
$ git checkout -b mybranch
------------

will create a new branch based at the current `HEAD` position, and switch
Junio C Hamano's avatar
Junio C Hamano committed
748
to it.
J. Bruce Fields's avatar
J. Bruce Fields committed
749 750 751 752 753

[NOTE]
================================================
If you make the decision to start your new branch at some
other point in the history than the current `HEAD`, you can do so by
754
just telling 'git checkout' what the base of the checkout would be.
J. Bruce Fields's avatar
J. Bruce Fields committed
755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777
In other words, if you have an earlier tag or branch, you'd just do

------------
$ git checkout -b mybranch earlier-commit
------------

and it would create the new branch `mybranch` at the earlier commit,
and check out the state at that time.
================================================

You can always just jump back to your original `master` branch by doing

------------
$ git checkout master
------------

(or any other branch-name, for that matter) and if you forget which
branch you happen to be on, a simple

------------
$ cat .git/HEAD
------------

778 779
will tell you where it's pointing.  To get the list of branches
you have, you can say
J. Bruce Fields's avatar
J. Bruce Fields committed
780 781 782 783 784

------------
$ git branch
------------

785 786
which used to be nothing more than a simple script around `ls .git/refs/heads`.
There will be an asterisk in front of the branch you are currently on.
J. Bruce Fields's avatar
J. Bruce Fields committed
787 788 789 790 791 792 793 794

Sometimes you may wish to create a new branch _without_ actually
checking it out and switching to it. If so, just use the command

------------
$ git branch <branchname> [startingpoint]
------------

Junio C Hamano's avatar
Junio C Hamano committed
795
which will simply _create_ the branch, but will not do anything further.
J. Bruce Fields's avatar
J. Bruce Fields committed
796
You can then later -- once you decide that you want to actually develop
797
on that branch -- switch to that branch with a regular 'git checkout'
J. Bruce Fields's avatar
J. Bruce Fields committed
798 799 800 801 802 803 804 805 806 807 808 809 810 811 812
with the branchname as the argument.


Merging two branches
--------------------

One of the ideas of having a branch is that you do some (possibly
experimental) work in it, and eventually merge it back to the main
branch. So assuming you created the above `mybranch` that started out
being the same as the original `master` branch, let's make sure we're in
that branch, and do some work there.

------------------------------------------------
$ git checkout mybranch
$ echo "Work, work, work" >>hello
813
$ git commit -m "Some work." -i hello
J. Bruce Fields's avatar
J. Bruce Fields committed
814 815 816
------------------------------------------------

Here, we just added another line to `hello`, and we used a shorthand for
817
doing both `git update-index hello` and `git commit` by just giving the
818
filename directly to `git commit`, with an `-i` flag (it tells
819
Git to 'include' that file in addition to what you have done to
820
the index file so far when making the commit).  The `-m` flag is to give the
J. Bruce Fields's avatar
J. Bruce Fields committed
821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837
commit log message from the command line.

Now, to make it a bit more interesting, let's assume that somebody else
does some work in the original branch, and simulate that by going back
to the master branch, and editing the same file differently there:

------------
$ git checkout master
------------

Here, take a moment to look at the contents of `hello`, and notice how they
don't contain the work we just did in `mybranch` -- because that work
hasn't happened in the `master` branch at all. Then do

------------
$ echo "Play, play, play" >>hello
$ echo "Lots of fun" >>example
838
$ git commit -m "Some fun." -i hello example
J. Bruce Fields's avatar
J. Bruce Fields committed
839 840 841 842 843 844 845 846 847 848 849 850
------------

since the master branch is obviously in a much better mood.

Now, you've got two branches, and you decide that you want to merge the
work done. Before we do that, let's introduce a cool graphical tool that
helps you view what's going on:

----------------
$ gitk --all
----------------

851
will show you graphically both of your branches (that's what the `--all`
J. Bruce Fields's avatar
J. Bruce Fields committed
852 853
means: normally it will just show you your current `HEAD`) and their
histories. You can also see exactly how they came to be from a common
Junio C Hamano's avatar
Junio C Hamano committed
854
source.
J. Bruce Fields's avatar
J. Bruce Fields committed
855

856
Anyway, let's exit 'gitk' (`^Q` or the File menu), and decide that we want
J. Bruce Fields's avatar
J. Bruce Fields committed
857 858
to merge the work we did on the `mybranch` branch into the `master`
branch (which is currently our `HEAD` too). To do that, there's a nice
859
script called 'git merge', which wants to know which branches you want
J. Bruce Fields's avatar
J. Bruce Fields committed
860 861 862
to resolve and what the merge is all about:

------------
863
$ git merge -m "Merge work in mybranch" mybranch
J. Bruce Fields's avatar
J. Bruce Fields committed
864 865 866 867 868 869
------------

where the first argument is going to be used as the commit message if
the merge can be resolved automatically.

Now, in this case we've intentionally created a situation where the
870
merge will need to be fixed up by hand, though, so Git will do as much
J. Bruce Fields's avatar
J. Bruce Fields committed
871 872 873 874
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:

----------------
Junio C Hamano's avatar
Junio C Hamano committed
875 876
	Auto-merging hello
	CONFLICT (content): Merge conflict in hello
877
	Automatic merge failed; fix conflicts and then commit the result.
J. Bruce Fields's avatar
J. Bruce Fields committed
878 879
----------------

880 881
It tells you that it did an "Automatic merge", which
failed due to conflicts in `hello`.
J. Bruce Fields's avatar
J. Bruce Fields committed
882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897

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
open `hello` in our editor (whatever that may be), and fix it up somehow.
I'd suggest just making it so that `hello` contains all four lines:

------------
Hello World
It's a new day for git
Play, play, play
Work, work, work
------------

and once you're happy with your manual merge, just do a

------------
898
$ git commit -i hello
J. Bruce Fields's avatar
J. Bruce Fields committed
899 900 901 902
------------

which will very loudly warn you that you're now committing a merge
(which is correct, so never mind), and you can write a small merge
903
message about your adventures in 'git merge'-land.
J. Bruce Fields's avatar
J. Bruce Fields committed
904

905
After you're done, start up `gitk --all` to see graphically what the
J. Bruce Fields's avatar
J. Bruce Fields committed
906 907 908
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
909
from the `master` branch, Git will know how you merged it, so you'll not
J. Bruce Fields's avatar
J. Bruce Fields committed
910 911 912 913 914 915
have to do _that_ merge again.

Another useful tool, especially if you do not always work in X-Window
environment, is `git show-branch`.

------------------------------------------------
916
$ git show-branch --topo-order --more=1 master mybranch
J. Bruce Fields's avatar
J. Bruce Fields committed
917 918 919 920 921
* [master] Merge work in mybranch
 ! [mybranch] Some work.
--
-  [master] Merge work in mybranch
*+ [mybranch] Some work.
922
*  [master^] Some fun.
J. Bruce Fields's avatar
J. Bruce Fields committed
923 924 925
------------------------------------------------

The first two lines indicate that it is showing the two branches
926 927 928
with the titles of their top-of-the-tree commits, you are currently on
`master` branch (notice the asterisk `*` character), and the first
column for the later output lines is used to show commits contained in the
J. Bruce Fields's avatar
J. Bruce Fields committed
929
`master` branch, and the second column for the `mybranch`
930
branch. Three commits are shown along with their titles.
931
All of them have non blank characters in the first column (`*`
932
shows an ordinary commit on the current branch, `-` is a merge commit), which
J. Bruce Fields's avatar
J. Bruce Fields committed
933 934 935 936 937 938
means they are now part of the `master` branch. Only the "Some
work" commit has the plus `+` character in the second column,
because `mybranch` has not been merged to incorporate these
commits from the master branch.  The string inside brackets
before the commit log message is a short name you can use to
name the commit.  In the above example, 'master' and 'mybranch'
939
are branch heads.  'master^' is the first parent of 'master'
940
branch head.  Please see linkgit:gitrevisions[7] if you want to
J. Bruce Fields's avatar
J. Bruce Fields committed
941 942
see more complex cases.

943
[NOTE]
944
Without the '--more=1' option, 'git show-branch' would not output the
945
'[master^]' commit, as '[mybranch]' commit is a common ancestor of
946 947
both 'master' and 'mybranch' tips.  Please see linkgit:git-show-branch[1]
for details.
948 949 950

[NOTE]
If there were more commits on the 'master' branch after the merge, the
951
merge commit itself would not be shown by 'git show-branch' by
952
default.  You would need to provide `--sparse` option to make the
953 954
merge commit visible in this case.

J. Bruce Fields's avatar
J. Bruce Fields committed
955 956 957
Now, let's pretend you are the one who did all the work in
`mybranch`, and the fruit of your hard work has finally been merged
to the `master` branch. Let's go back to `mybranch`, and run
958
'git merge' to get the "upstream changes" back to your branch.
J. Bruce Fields's avatar
J. Bruce Fields committed
959 960 961

------------
$ git checkout mybranch
962
$ git merge -m "Merge upstream changes." master
J. Bruce Fields's avatar
J. Bruce Fields committed
963 964 965 966 967 968 969
------------

This outputs something like this (the actual commit object names
would be different)

----------------
Updating from ae3a2da... to a80b4aa....
970
Fast-forward (no commit created; -m option ignored)
971 972
 example | 1 +
 hello   | 1 +
973
 2 files changed, 2 insertions(+)
J. Bruce Fields's avatar
J. Bruce Fields committed
974 975
----------------

976 977
Because your branch did not contain anything more than what had
already been merged into the `master` branch, the merge operation did
J. Bruce Fields's avatar
J. Bruce Fields committed
978 979
not actually do a merge. Instead, it just updated the top of
the tree of your branch to that of the `master` branch. This is
980
often called 'fast-forward' merge.
J. Bruce Fields's avatar
J. Bruce Fields committed
981

982
You can run `gitk --all` again to see how the commit ancestry
983
looks like, or run 'show-branch', which tells you this.
J. Bruce Fields's avatar
J. Bruce Fields committed
984 985 986 987 988 989 990 991 992 993 994 995 996 997

------------------------------------------------
$ git show-branch master mybranch
! [master] Merge work in mybranch
 * [mybranch] Merge work in mybranch
--
-- [master] Merge work in mybranch
------------------------------------------------


Merging external work
---------------------

It's usually much more common that you merge with somebody else than
998
merging with your own branches, so it's worth pointing out that Git
J. Bruce Fields's avatar
J. Bruce Fields committed
999
makes that very easy too, and in fact, it's not that different from
1000
doing a 'git merge'. In fact, a remote merge ends up being nothing
J. Bruce Fields's avatar
J. Bruce Fields committed
1001
more than "fetch the work from a remote repository into a temporary tag"
1002
followed by a 'git merge'.
J. Bruce Fields's avatar
J. Bruce Fields committed
1003 1004

Fetching from a remote repository is done by, unsurprisingly,
1005
'git fetch':
J. Bruce Fields's avatar
J. Bruce Fields committed
1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023

----------------
$ git fetch <remote-repository>
----------------

One of the following transports can be used to name the
repository to download from:

SSH::
	`remote.machine:/path/to/repo.git/` or
+
`ssh://remote.machine/path/to/repo.git/`
+
This transport can be used for both uploading and downloading,
and requires you to have a log-in privilege over `ssh` to the
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
1024
most efficient way to exchange Git objects between repositories.
J. Bruce Fields's avatar
J. Bruce Fields committed
1025 1026 1027 1028

Local directory::
	`/path/to/repo.git/`
+
1029
This transport is the same as SSH transport but uses 'sh' to run
J. Bruce Fields's avatar
J. Bruce Fields committed
1030
both ends on the local machine instead of running other end on
1031
the remote machine via 'ssh'.
J. Bruce Fields's avatar
J. Bruce Fields committed
1032

1033
Git Native::
J. Bruce Fields's avatar
J. Bruce Fields committed
1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046
	`git://remote.machine/path/to/repo.git/`
+
This transport was designed for anonymous downloading.  Like SSH
transport, it finds out the set of objects the downstream side
lacks and transfers (close to) minimum set of objects.

HTTP(S)::
	`http://remote.machine/path/to/repo.git/`
+
Downloader from http and https URL
first obtains the topmost commit object name from the remote site
by looking at the specified refname under `repo.git/refs/` directory,
and then tries to obtain the
1047
commit object by downloading from `repo.git/objects/xx/xxx...`
J. Bruce Fields's avatar
J. Bruce Fields committed
1048 1049 1050
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
1051
necessary objects.  Because of this behavior, they are
J. Bruce Fields's avatar
J. Bruce Fields committed
1052 1053 1054
sometimes also called 'commit walkers'.
+
The 'commit walkers' are sometimes also called 'dumb
1055 1056
transports', because they do not require any Git aware smart
server like Git Native transport does.  Any stock HTTP server
J. Bruce Fields's avatar
J. Bruce Fields committed
1057
that does not even support directory index would suffice.  But
1058
you must prepare your repository with 'git update-server-info'
J. Bruce Fields's avatar
J. Bruce Fields committed
1059 1060
to help dumb transport downloaders.

Junio C Hamano's avatar
Junio C Hamano committed
1061
Once you fetch from the remote repository, you `merge` that
J. Bruce Fields's avatar
J. Bruce Fields committed
1062 1063 1064
with your current branch.

However -- it's such a common thing to `fetch` and then
Junio C Hamano's avatar
Junio C Hamano committed
1065
immediately `merge`, that it's called `git pull`, and you can
J. Bruce Fields's avatar
J. Bruce Fields committed
1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077
simply do

----------------
$ git pull <remote-repository>
----------------

and optionally give a branch-name for the remote end as a second
argument.

[NOTE]
You could do without using any branches at all, by
keeping as many local repositories as you would like to have
1078
branches, and merging between them with 'git pull', just like
J. Bruce Fields's avatar
J. Bruce Fields committed
1079
you merge between branches. The advantage of this approach is
1080
that it lets you keep a set of files for each `branch` checked
J. Bruce Fields's avatar
J. Bruce Fields committed
1081 1082 1083 1084 1085 1086 1087
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.

It is likely that you will be pulling from the same remote
repository from time to time. As a short hand, you can store
Nicolas Pitre's avatar
Nicolas Pitre committed
1088 1089
the remote repository URL in the local repository's config file
like this:
J. Bruce Fields's avatar
J. Bruce Fields committed
1090 1091

------------------------------------------------
1092
$ git config remote.linus.url http://www.kernel.org/pub/scm/git/git.git/
J. Bruce Fields's avatar
J. Bruce Fields committed
1093 1094
------------------------------------------------

1095
and use the "linus" keyword with 'git pull' instead of the full URL.
J. Bruce Fields's avatar
J. Bruce Fields committed
1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121

Examples.

. `git pull linus`
. `git pull linus tag v0.99.1`

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`


How does the merge work?
------------------------

We said this tutorial shows what plumbing does to help you cope
with the porcelain that isn't flushing, but we so far did not
talk about how the merge really works.  If you are following
this tutorial the first time, I'd suggest to skip to "Publishing
your work" section and come back here later.

OK, still with me?  To give us an example to look at, let's go
back to the earlier repository with "hello" and "example" file,
and bring ourselves back to the pre-merge state:

------------
1122
$ git show-branch --more=2 master mybranch
J. Bruce Fields's avatar
J. Bruce Fields committed
1123 1124 1125 1126 1127 1128 1129 1130
! [master] Merge work in mybranch
 * [mybranch] Merge work in mybranch
--
-- [master] Merge work in mybranch
+* [master^2] Some work.
+* [master^] Some fun.
------------

1131
Remember, before running 'git merge', our `master` head was at
J. Bruce Fields's avatar
J. Bruce Fields committed
1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149
"Some fun." commit, while our `mybranch` head was at "Some
work." commit.

------------
$ git checkout mybranch
$ git reset --hard master^2
$ git checkout master
$ git reset --hard master^
------------

After rewinding, the commit structure should look like this:

------------
$ git show-branch
* [master] Some fun.
 ! [mybranch] Some work.
--
*  [master] Some fun.
1150 1151
 + [mybranch] Some work.
*+ [master^] Initial commit
J. Bruce Fields's avatar
J. Bruce Fields committed
1152 1153 1154 1155 1156 1157
------------

Now we are ready to experiment with the merge by hand.

`git merge` command, when merging two branches, uses 3-way merge
algorithm.  First, it finds the common ancestor between them.
1158
The command it uses is 'git merge-base':
J. Bruce Fields's avatar
J. Bruce Fields committed
1159 1160

------------
1161
$ mb=$(git merge-base HEAD mybranch)
J. Bruce Fields's avatar
J. Bruce Fields committed
1162 1163 1164 1165
------------

The command writes the commit object name of the common ancestor
to the standard output, so we captured its output to a variable,
1166
because we will be using it in the next step.  By the way, the common
1167
ancestor commit is the "Initial commit" commit in this case.  You can
J. Bruce Fields's avatar
J. Bruce Fields committed
1168 1169 1170
tell it by:

------------
1171
$ git name-rev --name-only --tags $mb
J. Bruce Fields's avatar
J. Bruce Fields committed
1172 1173 1174 1175 1176 1177 1178
my-first-tag
------------

After finding out a common ancestor commit, the second step is
this:

------------
1179
$ git read-tree -m -u $mb HEAD mybranch
J. Bruce Fields's avatar
J. Bruce Fields committed
1180 1181
------------

1182
This is the same 'git read-tree' command we have already seen,
J. Bruce Fields's avatar
J. Bruce Fields committed
1183 1184
but it takes three trees, unlike previous examples.  This reads
the contents of each tree into different 'stage' in the index
1185
file (the first tree goes to stage 1, the second to stage 2,
J. Bruce Fields's avatar
J. Bruce Fields committed
1186 1187 1188
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
1189
collapsed into stage 0, taking the SHA-1 from either stage 2 or
J. Bruce Fields's avatar
J. Bruce Fields committed
1190 1191 1192 1193 1194 1195 1196 1197
stage 3, whichever is different from stage 1 (i.e. only one side
changed from the common ancestor).

After 'collapsing' operation, paths that are different in three
trees are left in non-zero stages.  At this point, you can
inspect the index file with this command:

------------
1198
$ git ls-files --stage
J. Bruce Fields's avatar
J. Bruce Fields committed
1199
100644 7f8b141b65fdcee47321e399a2598a235a032422 0	example
1200 1201
100644 557db03de997c86a4a028e1ebd3a1ceb225be238 1	hello
100644 ba42a2a96e3027f3333e13ede4ccf4498c3ae942 2	hello
J. Bruce Fields's avatar
J. Bruce Fields committed
1202 1203 1204 1205
100644 cc44c73eb783565da5831b4d820c962954019b69 3	hello
------------

In our example of only two files, we did not have unchanged
1206 1207 1208 1209
files so only 'example' resulted in collapsing.  But in real-life
large projects, when only a small number of files change in one commit,
this 'collapsing' tends to trivially merge most of the paths
fairly quickly, leaving only a handful of real changes in non-zero
J. Bruce Fields's avatar
J. Bruce Fields committed
1210 1211
stages.

1212
To look at only non-zero stages, use `--unmerged` flag:
J. Bruce Fields's avatar
J. Bruce Fields committed
1213 1214

------------
1215
$ git ls-files --unmerged
1216 1217
100644 557db03de997c86a4a028e1ebd3a1ceb225be238 1	hello
100644 ba42a2a96e3027f3333e13ede4ccf4498c3ae942 2	hello
J. Bruce Fields's avatar
J. Bruce Fields committed
1218 1219 1220 1221 1222
100644 cc44c73eb783565da5831b4d820c962954019b69 3	hello
------------

The next step of merging is to merge these three versions of the
file, using 3-way merge.  This is done by giving
1223 1224
'git merge-one-file' command as one of the arguments to
'git merge-index' command:
J. Bruce Fields's avatar
J. Bruce Fields committed
1225 1226

------------
1227
$ git merge-index git-merge-one-file hello
1228 1229
Auto-merging hello
ERROR: Merge conflict in hello
J. Bruce Fields's avatar
J. Bruce Fields committed
1230 1231 1232
fatal: merge program failed
------------

1233
'git merge-one-file' script is called with parameters to
J. Bruce Fields's avatar
J. Bruce Fields committed
1234 1235 1236
describe those three versions, and is responsible to leave the
merge results in the working tree.
It is a fairly straightforward shell script, and
1237 1238
eventually calls 'merge' program from RCS suite to perform a
file-level 3-way merge.  In this case, 'merge' detects
J. Bruce Fields's avatar
J. Bruce Fields committed
1239 1240 1241 1242 1243
conflicts, and the merge result with conflict marks is left in
the working tree..  This can be seen if you run `ls-files
--stage` again at this point:

------------
1244
$ git ls-files --stage
J. Bruce Fields's avatar
J. Bruce Fields committed
1245
100644 7f8b141b65fdcee47321e399a2598a235a032422 0	example
1246 1247
100644 557db03de997c86a4a028e1ebd3a1ceb225be238 1	hello
100644 ba42a2a96e3027f3333e13ede4ccf4498c3ae942 2	hello
J. Bruce Fields's avatar
J. Bruce Fields committed
1248 1249 1250 1251
100644 cc44c73eb783565da5831b4d820c962954019b69 3	hello
------------

This is the state of the index file and the working file after
1252
'git merge' returns control back to you, leaving the conflicting
J. Bruce Fields's avatar
J. Bruce Fields committed
1253
merge for you to resolve.  Notice that the path `hello` is still
1254
unmerged, and what you see with 'git diff' at this point is
J. Bruce Fields's avatar
J. Bruce Fields committed
1255 1256 1257 1258 1259 1260
differences since stage 2 (i.e. your version).


Publishing your work
--------------------

1261
So, we can use somebody else's work from a remote repository, but
J. Bruce Fields's avatar
J. Bruce Fields committed
1262 1263 1264
how can *you* prepare a repository to let other people pull from
it?

1265
You do your real work in your working tree that has your
J. Bruce Fields's avatar
J. Bruce Fields committed
1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276
primary repository hanging under it as its `.git` subdirectory.
You *could* make that repository accessible remotely and ask
people to pull from it, but in practice that is not the way
things are usually done. A recommended way is to have a public
repository, make it reachable by other people, and when the
changes you made in your primary working tree are in good shape,
update the public repository from it. This is often called
'pushing'.

[NOTE]
This public repository could further be mirrored, and that is
1277
how Git repositories at `kernel.org` are managed.
J. Bruce Fields's avatar
J. Bruce Fields committed
1278 1279 1280 1281

Publishing the changes from your local (private) repository to
your remote (public) repository requires a write privilege on
the remote machine. You need to have an SSH account there to
1282
run a single command, 'git-receive-pack'.
J. Bruce Fields's avatar
J. Bruce Fields committed
1283 1284 1285 1286 1287 1288 1289 1290

First, you need to create an empty repository on the remote
machine that will house your public repository. This empty
repository will be populated and be kept up-to-date by pushing
into it later. Obviously, this repository creation needs to be
done only once.

[NOTE]
1291 1292
'git push' uses a pair of commands,
'git send-pack' on your local machine, and 'git-receive-pack'
J. Bruce Fields's avatar
J. Bruce Fields committed
1293 1294 1295
on the remote machine. The communication between the two over
the network internally uses an SSH connection.

1296
Your private repository's Git directory is usually `.git`, but
J. Bruce Fields's avatar
J. Bruce Fields committed
1297 1298 1299 1300 1301 1302 1303 1304 1305
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
an empty directory:

------------
$ mkdir my-git.git
------------

1306
Then, make that directory into a Git repository by running
1307
'git init', but this time, since its name is not the usual
J. Bruce Fields's avatar
J. Bruce Fields committed
1308 1309 1310
`.git`, we do things slightly differently:

------------
1311
$ GIT_DIR=my-git.git git init
J. Bruce Fields's avatar
J. Bruce Fields committed
1312 1313 1314
------------

Make sure this directory is available for others you want your
1315
changes to be pulled via the transport of your choice. Also
1316
you need to make sure that you have the 'git-receive-pack'
J. Bruce Fields's avatar
J. Bruce Fields committed
1317 1318 1319 1320 1321
program on the `$PATH`.

[NOTE]
Many installations of sshd do not invoke your shell as the login
shell when you directly run programs; what this means is that if
1322
your login shell is 'bash', only `.bashrc` is read and not