New tutorial
The current Documentation/tutorial.txt concentrates on the lower-level git interfaces. So it's useful to people developing alternative porcelains, to advanced users, etc., but not so much to beginning users. I think it makes sense for the main tutorial to address those beginnning users, so with this patch I'm proposing that we move Documentation/tutorial.txt to Documentation/core-tutorial.txt and replace it by a new tutorial. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu> Signed-off-by: Junio C Hamano <junkio@cox.net>
J. Bruce Fields committed
Jan 22, 2006 at 23:57 UTC
927a503cd07718ea0f700052043f383253904a56
2 files changed
+2107
-1701
Documentation/core-tutorial.txt
new
+1821
@@ -0,0 +1,1821 @@
1
+A short git tutorial
2
+====================
3
+
4
+Introduction
5
+------------
6
+
7
+This is trying to be a short tutorial on setting up and using a git
8
+repository, mainly because being hands-on and using explicit examples is
9
+often the best way of explaining what is going on.
10
+
11
+In normal life, most people wouldn't use the "core" git programs
12
+directly, but rather script around them to make them more palatable.
13
+Understanding the core git stuff may help some people get those scripts
14
+done, though, and it may also be instructive in helping people
15
+understand what it is that the higher-level helper scripts are actually
16
+doing.
17
+
18
+The core git is often called "plumbing", with the prettier user
19
+interfaces on top of it called "porcelain". You may not want to use the
20
+plumbing directly very often, but it can be good to know what the
21
+plumbing does for when the porcelain isn't flushing.
22
+
23
+The material presented here often goes deep describing how things
24
+work internally. If you are mostly interested in using git as a
25
+SCM, you can skip them during your first pass.
26
+
27
+[NOTE]
28
+And those "too deep" descriptions are often marked as Note.
29
+
30
+[NOTE]
31
+If you are already familiar with another version control system,
32
+like CVS, you may want to take a look at
33
+link:everyday.html[Everyday GIT in 20 commands or so] first
34
+before reading this.
35
+
36
+
37
+Creating a git repository
38
+-------------------------
39
+
40
+Creating a new git repository couldn't be easier: all git repositories start
41
+out empty, and the only thing you need to do is find yourself a
42
+subdirectory that you want to use as a working tree - either an empty
43
+one for a totally new project, or an existing working tree that you want
44
+to import into git.
45
+
46
+For our first example, we're going to start a totally new repository from
47
+scratch, with no pre-existing files, and we'll call it `git-tutorial`.
48
+To start up, create a subdirectory for it, change into that
49
+subdirectory, and initialize the git infrastructure with `git-init-db`:
50
+
51
+------------------------------------------------
52
+$ mkdir git-tutorial
53
+$ cd git-tutorial
54
+$ git-init-db
55
+------------------------------------------------
56
+
57
+to which git will reply
58
+
59
+----------------
60
+defaulting to local storage area
61
+----------------
62
+
63
+which is just git's way of saying that you haven't been doing anything
64
+strange, and that it will have created a local `.git` directory setup for
65
+your new project. You will now have a `.git` directory, and you can
66
+inspect that with `ls`. For your new empty project, it should show you
67
+three entries, among other things:
68
+
69
+ - a symlink called `HEAD`, pointing to `refs/heads/master` (if your
70
+ platform does not have native symlinks, it is a file containing the
71
+ line "ref: refs/heads/master")
72
++
73
+Don't worry about the fact that the file that the `HEAD` link points to
74
+doesn't even exist yet -- you haven't created the commit that will
75
+start your `HEAD` development branch yet.
76
+
77
+ - a subdirectory called `objects`, which will contain all the
78
+ objects of your project. You should never have any real reason to
79
+ look at the objects directly, but you might want to know that these
80
+ objects are what contains all the real 'data' in your repository.
81
+
82
+ - a subdirectory called `refs`, which contains references to objects.
83
+
84
+In particular, the `refs` subdirectory will contain two other
85
+subdirectories, named `heads` and `tags` respectively. They do
86
+exactly what their names imply: they contain references to any number
87
+of different 'heads' of development (aka 'branches'), and to any
88
+'tags' that you have created to name specific versions in your
89
+repository.
90
+
91
+One note: the special `master` head is the default branch, which is
92
+why the `.git/HEAD` file was created as a symlink to it even if it
93
+doesn't yet exist. Basically, the `HEAD` link is supposed to always
94
+point to the branch you are working on right now, and you always
95
+start out expecting to work on the `master` branch.
96
+
97
+However, this is only a convention, and you can name your branches
98
+anything you want, and don't have to ever even 'have' a `master`
99
+branch. A number of the git tools will assume that `.git/HEAD` is
100
+valid, though.
101
+
102
+[NOTE]
103
+An 'object' is identified by its 160-bit SHA1 hash, aka 'object name',
104
+and a reference to an object is always the 40-byte hex
105
+representation of that SHA1 name. The files in the `refs`
106
+subdirectory are expected to contain these hex references
107
+(usually with a final `\'\n\'` at the end), and you should thus
108
+expect to see a number of 41-byte files containing these
109
+references in these `refs` subdirectories when you actually start
110
+populating your tree.
111
+
112
+[NOTE]
113
+An advanced user may want to take a look at the
114
+link:repository-layout.html[repository layout] document
115
+after finishing this tutorial.
116
+
117
+You have now created your first git repository. Of course, since it's
118
+empty, that's not very useful, so let's start populating it with data.
119
+
120
+
121
+Populating a git repository
122
+---------------------------
123
+
124
+We'll keep this simple and stupid, so we'll start off with populating a
125
+few trivial files just to get a feel for it.
126
+
127
+Start off with just creating any random files that you want to maintain
128
+in your git repository. We'll start off with a few bad examples, just to
129
+get a feel for how this works:
130
+
131
+------------------------------------------------
132
+$ echo "Hello World" >hello
133
+$ echo "Silly example" >example
134
+------------------------------------------------
135
+
136
+you have now created two files in your working tree (aka 'working directory'), but to
137
+actually check in your hard work, you will have to go through two steps:
138
+
139
+ - fill in the 'index' file (aka 'cache') with the information about your
140
+ working tree state.
141
+
142
+ - commit that index file as an object.
143
+
144
+The first step is trivial: when you want to tell git about any changes
145
+to your working tree, you use the `git-update-index` program. That
146
+program normally just takes a list of filenames you want to update, but
147
+to avoid trivial mistakes, it refuses to add new entries to the index
148
+(or remove existing ones) unless you explicitly tell it that you're
149
+adding a new entry with the `\--add` flag (or removing an entry with the
150
+`\--remove`) flag.
151
+
152
+So to populate the index with the two files you just created, you can do
153
+
154
+------------------------------------------------
155
+$ git-update-index --add hello example
156
+------------------------------------------------
157
+
158
+and you have now told git to track those two files.
159
+
160
+In fact, as you did that, if you now look into your object directory,
161
+you'll notice that git will have added two new objects to the object
162
+database. If you did exactly the steps above, you should now be able to do
163
+
164
+
165
+----------------
166
+$ ls .git/objects/??/*
167
+----------------
168
+
169
+and see two files:
170
+
171
+----------------
172
+.git/objects/55/7db03de997c86a4a028e1ebd3a1ceb225be238
173
+.git/objects/f2/4c74a2e500f5ee1332c86b94199f52b1d1d962
174
+----------------
175
+
176
+which correspond with the objects with names of 557db... and f24c7..
177
+respectively.
178
+
179
+If you want to, you can use `git-cat-file` to look at those objects, but
180
+you'll have to use the object name, not the filename of the object:
181
+
182
+----------------
183
+$ git-cat-file -t 557db03de997c86a4a028e1ebd3a1ceb225be238
184
+----------------
185
+
186
+where the `-t` tells `git-cat-file` to tell you what the "type" of the
187
+object is. git will tell you that you have a "blob" object (ie just a
188
+regular file), and you can see the contents with
189
+
190
+----------------
191
+$ git-cat-file "blob" 557db03
192
+----------------
193
+
194
+which will print out "Hello World". The object 557db03 is nothing
195
+more than the contents of your file `hello`.
196
+
197
+[NOTE]
198
+Don't confuse that object with the file `hello` itself. The
199
+object is literally just those specific *contents* of the file, and
200
+however much you later change the contents in file `hello`, the object
201
+we just looked at will never change. Objects are immutable.
202
+
203
+[NOTE]
204
+The second example demonstrates that you can
205
+abbreviate the object name to only the first several
206
+hexadecimal digits in most places.
207
+
208
+Anyway, as we mentioned previously, you normally never actually take a
209
+look at the objects themselves, and typing long 40-character hex
210
+names is not something you'd normally want to do. The above digression
211
+was just to show that `git-update-index` did something magical, and
212
+actually saved away the contents of your files into the git object
213
+database.
214
+
215
+Updating the index did something else too: it created a `.git/index`
216
+file. This is the index that describes your current working tree, and
217
+something you should be very aware of. Again, you normally never worry
218
+about the index file itself, but you should be aware of the fact that
219
+you have not actually really "checked in" your files into git so far,
220
+you've only *told* git about them.
221
+
222
+However, since git knows about them, you can now start using some of the
223
+most basic git commands to manipulate the files or look at their status.
224
+
225
+In particular, let's not even check in the two files into git yet, we'll
226
+start off by adding another line to `hello` first:
227
+
228
+------------------------------------------------
229
+$ echo "It's a new day for git" >>hello
230
+------------------------------------------------
231
+
232
+and you can now, since you told git about the previous state of `hello`, ask
233
+git what has changed in the tree compared to your old index, using the
234
+`git-diff-files` command:
235
+
236
+------------
237
+$ git-diff-files
238
+------------
239
+
240
+Oops. That wasn't very readable. It just spit out its own internal
241
+version of a `diff`, but that internal version really just tells you
242
+that it has noticed that "hello" has been modified, and that the old object
243
+contents it had have been replaced with something else.
244
+
245
+To make it readable, we can tell git-diff-files to output the
246
+differences as a patch, using the `-p` flag:
247
+
248
+------------
249
+$ git-diff-files -p
250
+diff --git a/hello b/hello
251
+index 557db03..263414f 100644
252
+--- a/hello
253
++++ b/hello
254
+@@ -1 +1,2 @@
255
+ Hello World
256
++It's a new day for git
257
+----
258
+
259
+i.e. the diff of the change we caused by adding another line to `hello`.
260
+
261
+In other words, `git-diff-files` always shows us the difference between
262
+what is recorded in the index, and what is currently in the working
263
+tree. That's very useful.
264
+
265
+A common shorthand for `git-diff-files -p` is to just write `git
266
+diff`, which will do the same thing.
267
+
268
+------------
269
+$ git diff
270
+diff --git a/hello b/hello
271
+index 557db03..263414f 100644
272
+--- a/hello
273
++++ b/hello
274
+@@ -1 +1,2 @@
275
+ Hello World
276
++It's a new day for git
277
+------------
278
+
279
+
280
+Committing git state
281
+--------------------
282
+
283
+Now, we want to go to the next stage in git, which is to take the files
284
+that git knows about in the index, and commit them as a real tree. We do
285
+that in two phases: creating a 'tree' object, and committing that 'tree'
286
+object as a 'commit' object together with an explanation of what the
287
+tree was all about, along with information of how we came to that state.
288
+
289
+Creating a tree object is trivial, and is done with `git-write-tree`.
290
+There are no options or other input: git-write-tree will take the
291
+current index state, and write an object that describes that whole
292
+index. In other words, we're now tying together all the different
293
+filenames with their contents (and their permissions), and we're
294
+creating the equivalent of a git "directory" object:
295
+
296
+------------------------------------------------
297
+$ git-write-tree
298
+------------------------------------------------
299
+
300
+and this will just output the name of the resulting tree, in this case
301
+(if you have done exactly as I've described) it should be
302
+
303
+----------------
304
+8988da15d077d4829fc51d8544c097def6644dbb
305
+----------------
306
+
307
+which is another incomprehensible object name. Again, if you want to,
308
+you can use `git-cat-file -t 8988d\...` to see that this time the object
309
+is not a "blob" object, but a "tree" object (you can also use
310
+`git-cat-file` to actually output the raw object contents, but you'll see
311
+mainly a binary mess, so that's less interesting).
312
+
313
+However -- normally you'd never use `git-write-tree` on its own, because
314
+normally you always commit a tree into a commit object using the
315
+`git-commit-tree` command. In fact, it's easier to not actually use
316
+`git-write-tree` on its own at all, but to just pass its result in as an
317
+argument to `git-commit-tree`.
318
+
319
+`git-commit-tree` normally takes several arguments -- it wants to know
320
+what the 'parent' of a commit was, but since this is the first commit
321
+ever in this new repository, and it has no parents, we only need to pass in
322
+the object name of the tree. However, `git-commit-tree`
323
+also wants to get a commit message
324
+on its standard input, and it will write out the resulting object name for the
325
+commit to its standard output.
326
+
327
+And this is where we create the `.git/refs/heads/master` file
328
+which is pointed at by `HEAD`. This file is supposed to contain
329
+the reference to the top-of-tree of the master branch, and since
330
+that's exactly what `git-commit-tree` spits out, we can do this
331
+all with a sequence of simple shell commands:
332
+
333
+------------------------------------------------
334
+$ tree=$(git-write-tree)
335
+$ commit=$(echo 'Initial commit' | git-commit-tree $tree)
336
+$ git-update-ref HEAD $commit
337
+------------------------------------------------
338
+
339
+which will say:
340
+
341
+----------------
342
+Committing initial tree 8988da15d077d4829fc51d8544c097def6644dbb
343
+----------------
344
+
345
+just to warn you about the fact that it created a totally new commit
346
+that is not related to anything else. Normally you do this only *once*
347
+for a project ever, and all later commits will be parented on top of an
348
+earlier commit, and you'll never see this "Committing initial tree"
349
+message ever again.
350
+
351
+Again, normally you'd never actually do this by hand. There is a
352
+helpful script called `git commit` that will do all of this for you. So
353
+you could have just written `git commit`
354
+instead, and it would have done the above magic scripting for you.
355
+
356
+
357
+Making a change
358
+---------------
359
+
360
+Remember how we did the `git-update-index` on file `hello` and then we
361
+changed `hello` afterward, and could compare the new state of `hello` with the
362
+state we saved in the index file?
363
+
364
+Further, remember how I said that `git-write-tree` writes the contents
365
+of the *index* file to the tree, and thus what we just committed was in
366
+fact the *original* contents of the file `hello`, not the new ones. We did
367
+that on purpose, to show the difference between the index state, and the
368
+state in the working tree, and how they don't have to match, even
369
+when we commit things.
370
+
371
+As before, if we do `git-diff-files -p` in our git-tutorial project,
372
+we'll still see the same difference we saw last time: the index file
373
+hasn't changed by the act of committing anything. However, now that we
374
+have committed something, we can also learn to use a new command:
375
+`git-diff-index`.
376
+
377
+Unlike `git-diff-files`, which showed the difference between the index
378
+file and the working tree, `git-diff-index` shows the differences
379
+between a committed *tree* and either the index file or the working
380
+tree. In other words, `git-diff-index` wants a tree to be diffed
381
+against, and before we did the commit, we couldn't do that, because we
382
+didn't have anything to diff against.
383
+
384
+But now we can do
385
+
386
+----------------
387
+$ git-diff-index -p HEAD
388
+----------------
389
+
390
+(where `-p` has the same meaning as it did in `git-diff-files`), and it
391
+will show us the same difference, but for a totally different reason.
392
+Now we're comparing the working tree not against the index file,
393
+but against the tree we just wrote. It just so happens that those two
394
+are obviously the same, so we get the same result.
395
+
396
+Again, because this is a common operation, you can also just shorthand
397
+it with
398
+
399
+----------------
400
+$ git diff HEAD
401
+----------------
402
+
403
+which ends up doing the above for you.
404
+
405
+In other words, `git-diff-index` normally compares a tree against the
406
+working tree, but when given the `\--cached` flag, it is told to
407
+instead compare against just the index cache contents, and ignore the
408
+current working tree state entirely. Since we just wrote the index
409
+file to HEAD, doing `git-diff-index \--cached -p HEAD` should thus return
410
+an empty set of differences, and that's exactly what it does.
411
+
412
+[NOTE]
413
+================
414
+`git-diff-index` really always uses the index for its
415
+comparisons, and saying that it compares a tree against the working
416
+tree is thus not strictly accurate. In particular, the list of
417
+files to compare (the "meta-data") *always* comes from the index file,
418
+regardless of whether the `\--cached` flag is used or not. The `\--cached`
419
+flag really only determines whether the file *contents* to be compared
420
+come from the working tree or not.
421
+
422
+This is not hard to understand, as soon as you realize that git simply
423
+never knows (or cares) about files that it is not told about
424
+explicitly. git will never go *looking* for files to compare, it
425
+expects you to tell it what the files are, and that's what the index
426
+is there for.
427
+================
428
+
429
+However, our next step is to commit the *change* we did, and again, to
430
+understand what's going on, keep in mind the difference between "working
431
+tree contents", "index file" and "committed tree". We have changes
432
+in the working tree that we want to commit, and we always have to
433
+work through the index file, so the first thing we need to do is to
434
+update the index cache:
435
+
436
+------------------------------------------------
437
+$ git-update-index hello
438
+------------------------------------------------
439
+
440
+(note how we didn't need the `\--add` flag this time, since git knew
441
+about the file already).
442
+
443
+Note what happens to the different `git-diff-\*` versions here. After
444
+we've updated `hello` in the index, `git-diff-files -p` now shows no
445
+differences, but `git-diff-index -p HEAD` still *does* show that the
446
+current state is different from the state we committed. In fact, now
447
+`git-diff-index` shows the same difference whether we use the `--cached`
448
+flag or not, since now the index is coherent with the working tree.
449
+
450
+Now, since we've updated `hello` in the index, we can commit the new
451
+version. We could do it by writing the tree by hand again, and
452
+committing the tree (this time we'd have to use the `-p HEAD` flag to
453
+tell commit that the HEAD was the *parent* of the new commit, and that
454
+this wasn't an initial commit any more), but you've done that once
455
+already, so let's just use the helpful script this time:
456
+
457
+------------------------------------------------
458
+$ git commit
459
+------------------------------------------------
460
+
461
+which starts an editor for you to write the commit message and tells you
462
+a bit about what you have done.
463
+
464
+Write whatever message you want, and all the lines that start with '#'
465
+will be pruned out, and the rest will be used as the commit message for
466
+the change. If you decide you don't want to commit anything after all at
467
+this point (you can continue to edit things and update the index), you
468
+can just leave an empty message. Otherwise `git commit` will commit
469
+the change for you.
470
+
471
+You've now made your first real git commit. And if you're interested in
472
+looking at what `git commit` really does, feel free to investigate:
473
+it's a few very simple shell scripts to generate the helpful (?) commit
474
+message headers, and a few one-liners that actually do the
475
+commit itself (`git-commit`).
476
+
477
+
478
+Inspecting Changes
479
+------------------
480
+
481
+While creating changes is useful, it's even more useful if you can tell
482
+later what changed. The most useful command for this is another of the
483
+`diff` family, namely `git-diff-tree`.
484
+
485
+`git-diff-tree` can be given two arbitrary trees, and it will tell you the
486
+differences between them. Perhaps even more commonly, though, you can
487
+give it just a single commit object, and it will figure out the parent
488
+of that commit itself, and show the difference directly. Thus, to get
489
+the same diff that we've already seen several times, we can now do
490
+
491
+----------------
492
+$ git-diff-tree -p HEAD
493
+----------------
494
+
495
+(again, `-p` means to show the difference as a human-readable patch),
496
+and it will show what the last commit (in `HEAD`) actually changed.
497
+
498
+[NOTE]
499
+============
500
+Here is an ASCII art by Jon Loeliger that illustrates how
501
+various diff-\* commands compare things.
502
+
503
+ diff-tree
504
+ +----+
505
+ | |
506
+ | |
507
+ V V
508
+ +-----------+
509
+ | Object DB |
510
+ | Backing |
511
+ | Store |
512
+ +-----------+
513
+ ^ ^
514
+ | |
515
+ | | diff-index --cached
516
+ | |
517
+ diff-index | V
518
+ | +-----------+
519
+ | | Index |
520
+ | | "cache" |
521
+ | +-----------+
522
+ | ^
523
+ | |
524
+ | | diff-files
525
+ | |
526
+ V V
527
+ +-----------+
528
+ | Working |
529
+ | Directory |
530
+ +-----------+
531
+============
532
+
533
+More interestingly, you can also give `git-diff-tree` the `-v` flag, which
534
+tells it to also show the commit message and author and date of the
535
+commit, and you can tell it to show a whole series of diffs.
536
+Alternatively, you can tell it to be "silent", and not show the diffs at
537
+all, but just show the actual commit message.
538
+
539
+In fact, together with the `git-rev-list` program (which generates a
540
+list of revisions), `git-diff-tree` ends up being a veritable fount of
541
+changes. A trivial (but very useful) script called `git-whatchanged` is
542
+included with git which does exactly this, and shows a log of recent
543
+activities.
544
+
545
+To see the whole history of our pitiful little git-tutorial project, you
546
+can do
547
+
548
+----------------
549
+$ git log
550
+----------------
551
+
552
+which shows just the log messages, or if we want to see the log together
553
+with the associated patches use the more complex (and much more
554
+powerful)
555
+
556
+----------------
557
+$ git-whatchanged -p --root
558
+----------------
559
+
560
+and you will see exactly what has changed in the repository over its
561
+short history.
562
+
563
+[NOTE]
564
+The `\--root` flag is a flag to `git-diff-tree` to tell it to
565
+show the initial aka 'root' commit too. Normally you'd probably not
566
+want to see the initial import diff, but since the tutorial project
567
+was started from scratch and is so small, we use it to make the result
568
+a bit more interesting.
569
+
570
+With that, you should now be having some inkling of what git does, and
571
+can explore on your own.
572
+
573
+[NOTE]
574
+Most likely, you are not directly using the core
575
+git Plumbing commands, but using Porcelain like Cogito on top
576
+of it. Cogito works a bit differently and you usually do not
577
+have to run `git-update-index` yourself for changed files (you
578
+do tell underlying git about additions and removals via
579
+`cg-add` and `cg-rm` commands). Just before you make a commit
580
+with `cg-commit`, Cogito figures out which files you modified,
581
+and runs `git-update-index` on them for you.
582
+
583
+
584
+Tagging a version
585
+-----------------
586
+
587
+In git, there are two kinds of tags, a "light" one, and an "annotated tag".
588
+
589
+A "light" tag is technically nothing more than a branch, except we put
590
+it in the `.git/refs/tags/` subdirectory instead of calling it a `head`.
591
+So the simplest form of tag involves nothing more than
592
+
593
+------------------------------------------------
594
+$ git tag my-first-tag
595
+------------------------------------------------
596
+
597
+which just writes the current `HEAD` into the `.git/refs/tags/my-first-tag`
598
+file, after which point you can then use this symbolic name for that
599
+particular state. You can, for example, do
600
+
601
+----------------
602
+$ git diff my-first-tag
603
+----------------
604
+
605
+to diff your current state against that tag (which at this point will
606
+obviously be an empty diff, but if you continue to develop and commit
607
+stuff, you can use your tag as an "anchor-point" to see what has changed
608
+since you tagged it.
609
+
610
+An "annotated tag" is actually a real git object, and contains not only a
611
+pointer to the state you want to tag, but also a small tag name and
612
+message, along with optionally a PGP signature that says that yes,
613
+you really did
614
+that tag. You create these annotated tags with either the `-a` or
615
+`-s` flag to `git tag`:
616
+
617
+----------------
618
+$ git tag -s <tagname>
619
+----------------
620
+
621
+which will sign the current `HEAD` (but you can also give it another
622
+argument that specifies the thing to tag, ie you could have tagged the
623
+current `mybranch` point by using `git tag <tagname> mybranch`).
624
+
625
+You normally only do signed tags for major releases or things
626
+like that, while the light-weight tags are useful for any marking you
627
+want to do -- any time you decide that you want to remember a certain
628
+point, just create a private tag for it, and you have a nice symbolic
629
+name for the state at that point.
630
+
631
+
632
+Copying repositories
633
+--------------------
634
+
635
+git repositories are normally totally self-sufficient and relocatable
636
+Unlike CVS, for example, there is no separate notion of
637
+"repository" and "working tree". A git repository normally *is* the
638
+working tree, with the local git information hidden in the `.git`
639
+subdirectory. There is nothing else. What you see is what you got.
640
+
641
+[NOTE]
642
+You can tell git to split the git internal information from
643
+the directory that it tracks, but we'll ignore that for now: it's not
644
+how normal projects work, and it's really only meant for special uses.
645
+So the mental model of "the git information is always tied directly to
646
+the working tree that it describes" may not be technically 100%
647
+accurate, but it's a good model for all normal use.
648
+
649
+This has two implications:
650
+
651
+ - if you grow bored with the tutorial repository you created (or you've
652
+ made a mistake and want to start all over), you can just do simple
653
++
654
+----------------
655
+$ rm -rf git-tutorial
656
+----------------
657
++
658
+and it will be gone. There's no external repository, and there's no
659
+history outside the project you created.
660
+
661
+ - if you want to move or duplicate a git repository, you can do so. There
662
+ is `git clone` command, but if all you want to do is just to
663
+ create a copy of your repository (with all the full history that
664
+ went along with it), you can do so with a regular
665
+ `cp -a git-tutorial new-git-tutorial`.
666
++
667
+Note that when you've moved or copied a git repository, your git index
668
+file (which caches various information, notably some of the "stat"
669
+information for the files involved) will likely need to be refreshed.
670
+So after you do a `cp -a` to create a new copy, you'll want to do
671
++
672
+----------------
673
+$ git-update-index --refresh
674
+----------------
675
++
676
+in the new repository to make sure that the index file is up-to-date.
677
+
678
+Note that the second point is true even across machines. You can
679
+duplicate a remote git repository with *any* regular copy mechanism, be it
680
+`scp`, `rsync` or `wget`.
681
+
682
+When copying a remote repository, you'll want to at a minimum update the
683
+index cache when you do this, and especially with other peoples'
684
+repositories you often want to make sure that the index cache is in some
685
+known state (you don't know *what* they've done and not yet checked in),
686
+so usually you'll precede the `git-update-index` with a
687
+
688
+----------------
689
+$ git-read-tree --reset HEAD
690
+$ git-update-index --refresh
691
+----------------
692
+
693
+which will force a total index re-build from the tree pointed to by `HEAD`.
694
+It resets the index contents to `HEAD`, and then the `git-update-index`
695
+makes sure to match up all index entries with the checked-out files.
696
+If the original repository had uncommitted changes in its
697
+working tree, `git-update-index --refresh` notices them and
698
+tells you they need to be updated.
699
+
700
+The above can also be written as simply
701
+
702
+----------------
703
+$ git reset
704
+----------------
705
+
706
+and in fact a lot of the common git command combinations can be scripted
707
+with the `git xyz` interfaces. You can learn things by just looking
708
+at what the various git scripts do. For example, `git reset` is the
709
+above two lines implemented in `git-reset`, but some things like
710
+`git status` and `git commit` are slightly more complex scripts around
711
+the basic git commands.
712
+
713
+Many (most?) public remote repositories will not contain any of
714
+the checked out files or even an index file, and will *only* contain the
715
+actual core git files. Such a repository usually doesn't even have the
716
+`.git` subdirectory, but has all the git files directly in the
717
+repository.
718
+
719
+To create your own local live copy of such a "raw" git repository, you'd
720
+first create your own subdirectory for the project, and then copy the
721
+raw repository contents into the `.git` directory. For example, to
722
+create your own copy of the git repository, you'd do the following
723
+
724
+----------------
725
+$ mkdir my-git
726
+$ cd my-git
727
+$ rsync -rL rsync://rsync.kernel.org/pub/scm/git/git.git/ .git
728
+----------------
729
+
730
+followed by
731
+
732
+----------------
733
+$ git-read-tree HEAD
734
+----------------
735
+
736
+to populate the index. However, now you have populated the index, and
737
+you have all the git internal files, but you will notice that you don't
738
+actually have any of the working tree files to work on. To get
739
+those, you'd check them out with
740
+
741
+----------------
742
+$ git-checkout-index -u -a
743
+----------------
744
+
745
+where the `-u` flag means that you want the checkout to keep the index
746
+up-to-date (so that you don't have to refresh it afterward), and the
747
+`-a` flag means "check out all files" (if you have a stale copy or an
748
+older version of a checked out tree you may also need to add the `-f`
749
+flag first, to tell git-checkout-index to *force* overwriting of any old
750
+files).
751
+
752
+Again, this can all be simplified with
753
+
754
+----------------
755
+$ git clone rsync://rsync.kernel.org/pub/scm/git/git.git/ my-git
756
+$ cd my-git
757
+$ git checkout
758
+----------------
759
+
760
+which will end up doing all of the above for you.
761
+
762
+You have now successfully copied somebody else's (mine) remote
763
+repository, and checked it out.
764
+
765
+
766
+Creating a new branch
767
+---------------------
768
+
769
+Branches in git are really nothing more than pointers into the git
770
+object database from within the `.git/refs/` subdirectory, and as we
771
+already discussed, the `HEAD` branch is nothing but a symlink to one of
772
+these object pointers.
773
+
774
+You can at any time create a new branch by just picking an arbitrary
775
+point in the project history, and just writing the SHA1 name of that
776
+object into a file under `.git/refs/heads/`. You can use any filename you
777
+want (and indeed, subdirectories), but the convention is that the
778
+"normal" branch is called `master`. That's just a convention, though,
779
+and nothing enforces it.
780
+
781
+To show that as an example, let's go back to the git-tutorial repository we
782
+used earlier, and create a branch in it. You do that by simply just
783
+saying that you want to check out a new branch:
784
+
785
+------------
786
+$ git checkout -b mybranch
787
+------------
788
+
789
+will create a new branch based at the current `HEAD` position, and switch
790
+to it.
791
+
792
+[NOTE]
793
+================================================
794
+If you make the decision to start your new branch at some
795
+other point in the history than the current `HEAD`, you can do so by
796
+just telling `git checkout` what the base of the checkout would be.
797
+In other words, if you have an earlier tag or branch, you'd just do
798
+
799
+------------
800
+$ git checkout -b mybranch earlier-commit
801
+------------
802
+
803
+and it would create the new branch `mybranch` at the earlier commit,
804
+and check out the state at that time.
805
+================================================
806
+
807
+You can always just jump back to your original `master` branch by doing
808
+
809
+------------
810
+$ git checkout master
811
+------------
812
+
813
+(or any other branch-name, for that matter) and if you forget which
814
+branch you happen to be on, a simple
815
+
816
+------------
817
+$ ls -l .git/HEAD
818
+------------
819
+
820
+will tell you where it's pointing (Note that on platforms with bad or no
821
+symlink support, you have to execute
822
+
823
+------------
824
+$ cat .git/HEAD
825
+------------
826
+
827
+instead). To get the list of branches you have, you can say
828
+
829
+------------
830
+$ git branch
831
+------------
832
+
833
+which is nothing more than a simple script around `ls .git/refs/heads`.
834
+There will be asterisk in front of the branch you are currently on.
835
+
836
+Sometimes you may wish to create a new branch _without_ actually
837
+checking it out and switching to it. If so, just use the command
838
+
839
+------------
840
+$ git branch <branchname> [startingpoint]
841
+------------
842
+
843
+which will simply _create_ the branch, but will not do anything further.
844
+You can then later -- once you decide that you want to actually develop
845
+on that branch -- switch to that branch with a regular `git checkout`
846
+with the branchname as the argument.
847
+
848
+
849
+Merging two branches
850
+--------------------
851
+
852
+One of the ideas of having a branch is that you do some (possibly
853
+experimental) work in it, and eventually merge it back to the main
854
+branch. So assuming you created the above `mybranch` that started out
855
+being the same as the original `master` branch, let's make sure we're in
856
+that branch, and do some work there.
857
+
858
+------------------------------------------------
859
+$ git checkout mybranch
860
+$ echo "Work, work, work" >>hello
861
+$ git commit -m 'Some work.' hello
862
+------------------------------------------------
863
+
864
+Here, we just added another line to `hello`, and we used a shorthand for
865
+doing both `git-update-index hello` and `git commit` by just giving the
866
+filename directly to `git commit`. The `-m` flag is to give the
867
+commit log message from the command line.
868
+
869
+Now, to make it a bit more interesting, let's assume that somebody else
870
+does some work in the original branch, and simulate that by going back
871
+to the master branch, and editing the same file differently there:
872
+
873
+------------
874
+$ git checkout master
875
+------------
876
+
877
+Here, take a moment to look at the contents of `hello`, and notice how they
878
+don't contain the work we just did in `mybranch` -- because that work
879
+hasn't happened in the `master` branch at all. Then do
880
+
881
+------------
882
+$ echo "Play, play, play" >>hello
883
+$ echo "Lots of fun" >>example
884
+$ git commit -m 'Some fun.' hello example
885
+------------
886
+
887
+since the master branch is obviously in a much better mood.
888
+
889
+Now, you've got two branches, and you decide that you want to merge the
890
+work done. Before we do that, let's introduce a cool graphical tool that
891
+helps you view what's going on:
892
+
893
+----------------
894
+$ gitk --all
895
+----------------
896
+
897
+will show you graphically both of your branches (that's what the `\--all`
898
+means: normally it will just show you your current `HEAD`) and their
899
+histories. You can also see exactly how they came to be from a common
900
+source.
901
+
902
+Anyway, let's exit `gitk` (`^Q` or the File menu), and decide that we want
903
+to merge the work we did on the `mybranch` branch into the `master`
904
+branch (which is currently our `HEAD` too). To do that, there's a nice
905
+script called `git merge`, which wants to know which branches you want
906
+to resolve and what the merge is all about:
907
+
908
+------------
909
+$ git merge "Merge work in mybranch" HEAD mybranch
910
+------------
911
+
912
+where the first argument is going to be used as the commit message if
913
+the merge can be resolved automatically.
914
+
915
+Now, in this case we've intentionally created a situation where the
916
+merge will need to be fixed up by hand, though, so git will do as much
917
+of it as it can automatically (which in this case is just merge the `example`
918
+file, which had no differences in the `mybranch` branch), and say:
919
+
920
+----------------
921
+ Trying really trivial in-index merge...
922
+ fatal: Merge requires file-level merging
923
+ Nope.
924
+ ...
925
+ Auto-merging hello
926
+ CONFLICT (content): Merge conflict in hello
927
+ Automatic merge failed/prevented; fix up by hand
928
+----------------
929
+
930
+which is way too verbose, but it basically tells you that it failed the
931
+really trivial merge ("Simple merge") and did an "Automatic merge"
932
+instead, but that too failed due to conflicts in `hello`.
933
+
934
+Not to worry. It left the (trivial) conflict in `hello` in the same form you
935
+should already be well used to if you've ever used CVS, so let's just
936
+open `hello` in our editor (whatever that may be), and fix it up somehow.
937
+I'd suggest just making it so that `hello` contains all four lines:
938
+
939
+------------
940
+Hello World
941
+It's a new day for git
942
+Play, play, play
943
+Work, work, work
944
+------------
945
+
946
+and once you're happy with your manual merge, just do a
947
+
948
+------------
949
+$ git commit hello
950
+------------
951
+
952
+which will very loudly warn you that you're now committing a merge
953
+(which is correct, so never mind), and you can write a small merge
954
+message about your adventures in git-merge-land.
955
+
956
+After you're done, start up `gitk \--all` to see graphically what the
957
+history looks like. Notice that `mybranch` still exists, and you can
958
+switch to it, and continue to work with it if you want to. The
959
+`mybranch` branch will not contain the merge, but next time you merge it
960
+from the `master` branch, git will know how you merged it, so you'll not
961
+have to do _that_ merge again.
962
+
963
+Another useful tool, especially if you do not always work in X-Window
964
+environment, is `git show-branch`.
965
+
966
+------------------------------------------------
967
+$ git show-branch master mybranch
968
+* [master] Merge work in mybranch
969
+ ! [mybranch] Some work.
970
+--
971
+- [master] Merge work in mybranch
972
+*+ [mybranch] Some work.
973
+------------------------------------------------
974
+
975
+The first two lines indicate that it is showing the two branches
976
+and the first line of the commit log message from their
977
+top-of-the-tree commits, you are currently on `master` branch
978
+(notice the asterisk `*` character), and the first column for
979
+the later output lines is used to show commits contained in the
980
+`master` branch, and the second column for the `mybranch`
981
+branch. Three commits are shown along with their log messages.
982
+All of them have non blank characters in the first column (`*`
983
+shows an ordinary commit on the current branch, `.` is a merge commit), which
984
+means they are now part of the `master` branch. Only the "Some
985
+work" commit has the plus `+` character in the second column,
986
+because `mybranch` has not been merged to incorporate these
987
+commits from the master branch. The string inside brackets
988
+before the commit log message is a short name you can use to
989
+name the commit. In the above example, 'master' and 'mybranch'
990
+are branch heads. 'master~1' is the first parent of 'master'
991
+branch head. Please see 'git-rev-parse' documentation if you
992
+see more complex cases.
993
+
994
+Now, let's pretend you are the one who did all the work in
995
+`mybranch`, and the fruit of your hard work has finally been merged
996
+to the `master` branch. Let's go back to `mybranch`, and run
997
+resolve to get the "upstream changes" back to your branch.
998
+
999
+------------
1000
+$ git checkout mybranch
1001
+$ git merge "Merge upstream changes." HEAD master
1002
+------------
1003
+
1004
+This outputs something like this (the actual commit object names
1005
+would be different)
1006
+
1007
+----------------
1008
+Updating from ae3a2da... to a80b4aa....
1009
+ example | 1 +
1010
+ hello | 1 +
1011
+ 2 files changed, 2 insertions(+), 0 deletions(-)
1012
+----------------
1013
+
1014
+Because your branch did not contain anything more than what are
1015
+already merged into the `master` branch, the resolve operation did
1016
+not actually do a merge. Instead, it just updated the top of
1017
+the tree of your branch to that of the `master` branch. This is
1018
+often called 'fast forward' merge.
1019
+
1020
+You can run `gitk \--all` again to see how the commit ancestry
1021
+looks like, or run `show-branch`, which tells you this.
1022
+
1023
+------------------------------------------------
1024
+$ git show-branch master mybranch
1025
+! [master] Merge work in mybranch
1026
+ * [mybranch] Merge work in mybranch
1027
+--
1028
+-- [master] Merge work in mybranch
1029
+------------------------------------------------
1030
+
1031
+
1032
+Merging external work
1033
+---------------------
1034
+
1035
+It's usually much more common that you merge with somebody else than
1036
+merging with your own branches, so it's worth pointing out that git
1037
+makes that very easy too, and in fact, it's not that different from
1038
+doing a `git merge`. In fact, a remote merge ends up being nothing
1039
+more than "fetch the work from a remote repository into a temporary tag"
1040
+followed by a `git merge`.
1041
+
1042
+Fetching from a remote repository is done by, unsurprisingly,
1043
+`git fetch`:
1044
+
1045
+----------------
1046
+$ git fetch <remote-repository>
1047
+----------------
1048
+
1049
+One of the following transports can be used to name the
1050
+repository to download from:
1051
+
1052
+Rsync::
1053
+ `rsync://remote.machine/path/to/repo.git/`
1054
++
1055
+Rsync transport is usable for both uploading and downloading,
1056
+but is completely unaware of what git does, and can produce
1057
+unexpected results when you download from the public repository
1058
+while the repository owner is uploading into it via `rsync`
1059
+transport. Most notably, it could update the files under
1060
+`refs/` which holds the object name of the topmost commits
1061
+before uploading the files in `objects/` -- the downloader would
1062
+obtain head commit object name while that object itself is still
1063
+not available in the repository. For this reason, it is
1064
+considered deprecated.
1065
+
1066
+SSH::
1067
+ `remote.machine:/path/to/repo.git/` or
1068
++
1069
+`ssh://remote.machine/path/to/repo.git/`
1070
++
1071
+This transport can be used for both uploading and downloading,
1072
+and requires you to have a log-in privilege over `ssh` to the
1073
+remote machine. It finds out the set of objects the other side
1074
+lacks by exchanging the head commits both ends have and
1075
+transfers (close to) minimum set of objects. It is by far the
1076
+most efficient way to exchange git objects between repositories.
1077
+
1078
+Local directory::
1079
+ `/path/to/repo.git/`
1080
++
1081
+This transport is the same as SSH transport but uses `sh` to run
1082
+both ends on the local machine instead of running other end on
1083
+the remote machine via `ssh`.
1084
+
1085
+git Native::
1086
+ `git://remote.machine/path/to/repo.git/`
1087
++
1088
+This transport was designed for anonymous downloading. Like SSH
1089
+transport, it finds out the set of objects the downstream side
1090
+lacks and transfers (close to) minimum set of objects.
1091
+
1092
+HTTP(S)::
1093
+ `http://remote.machine/path/to/repo.git/`
1094
++
1095
+Downloader from http and https URL
1096
+first obtains the topmost commit object name from the remote site
1097
+by looking at the specified refname under `repo.git/refs/` directory,
1098
+and then tries to obtain the
1099
+commit object by downloading from `repo.git/objects/xx/xxx\...`
1100
+using the object name of that commit object. Then it reads the
1101
+commit object to find out its parent commits and the associate
1102
+tree object; it repeats this process until it gets all the
1103
+necessary objects. Because of this behaviour, they are
1104
+sometimes also called 'commit walkers'.
1105
++
1106
+The 'commit walkers' are sometimes also called 'dumb
1107
+transports', because they do not require any git aware smart
1108
+server like git Native transport does. Any stock HTTP server
1109
+that does not even support directory index would suffice. But
1110
+you must prepare your repository with `git-update-server-info`
1111
+to help dumb transport downloaders.
1112
++
1113
+There are (confusingly enough) `git-ssh-fetch` and `git-ssh-upload`
1114
+programs, which are 'commit walkers'; they outlived their
1115
+usefulness when git Native and SSH transports were introduced,
1116
+and not used by `git pull` or `git push` scripts.
1117
+
1118
+Once you fetch from the remote repository, you `resolve` that
1119
+with your current branch.
1120
+
1121
+However -- it's such a common thing to `fetch` and then
1122
+immediately `resolve`, that it's called `git pull`, and you can
1123
+simply do
1124
+
1125
+----------------
1126
+$ git pull <remote-repository>
1127
+----------------
1128
+
1129
+and optionally give a branch-name for the remote end as a second
1130
+argument.
1131
+
1132
+[NOTE]
1133
+You could do without using any branches at all, by
1134
+keeping as many local repositories as you would like to have
1135
+branches, and merging between them with `git pull`, just like
1136
+you merge between branches. The advantage of this approach is
1137
+that it lets you keep set of files for each `branch` checked
1138
+out and you may find it easier to switch back and forth if you
1139
+juggle multiple lines of development simultaneously. Of
1140
+course, you will pay the price of more disk usage to hold
1141
+multiple working trees, but disk space is cheap these days.
1142
+
1143
+[NOTE]
1144
+You could even pull from your own repository by
1145
+giving '.' as <remote-repository> parameter to `git pull`. This
1146
+is useful when you want to merge a local branch (or more, if you
1147
+are making an Octopus) into the current branch.
1148
+
1149
+It is likely that you will be pulling from the same remote
1150
+repository from time to time. As a short hand, you can store
1151
+the remote repository URL in a file under .git/remotes/
1152
+directory, like this:
1153
+
1154
+------------------------------------------------
1155
+$ mkdir -p .git/remotes/
1156
+$ cat >.git/remotes/linus <<\EOF
1157
+URL: http://www.kernel.org/pub/scm/git/git.git/
1158
+EOF
1159
+------------------------------------------------
1160
+
1161
+and use the filename to `git pull` instead of the full URL.
1162
+The URL specified in such file can even be a prefix
1163
+of a full URL, like this:
1164
+
1165
+------------------------------------------------
1166
+$ cat >.git/remotes/jgarzik <<\EOF
1167
+URL: http://www.kernel.org/pub/scm/linux/git/jgarzik/
1168
+EOF
1169
+------------------------------------------------
1170
+
1171
+
1172
+Examples.
1173
+
1174
+. `git pull linus`
1175
+. `git pull linus tag v0.99.1`
1176
+. `git pull jgarzik/netdev-2.6.git/ e100`
1177
+
1178
+the above are equivalent to:
1179
+
1180
+. `git pull http://www.kernel.org/pub/scm/git/git.git/ HEAD`
1181
+. `git pull http://www.kernel.org/pub/scm/git/git.git/ tag v0.99.1`
1182
+. `git pull http://www.kernel.org/pub/.../jgarzik/netdev-2.6.git e100`
1183
+
1184
+
1185
+How does the merge work?
1186
+------------------------
1187
+
1188
+We said this tutorial shows what plumbing does to help you cope
1189
+with the porcelain that isn't flushing, but we so far did not
1190
+talk about how the merge really works. If you are following
1191
+this tutorial the first time, I'd suggest to skip to "Publishing
1192
+your work" section and come back here later.
1193
+
1194
+OK, still with me? To give us an example to look at, let's go
1195
+back to the earlier repository with "hello" and "example" file,
1196
+and bring ourselves back to the pre-merge state:
1197
+
1198
+------------
1199
+$ git show-branch --more=3 master mybranch
1200
+! [master] Merge work in mybranch
1201
+ * [mybranch] Merge work in mybranch
1202
+--
1203
+-- [master] Merge work in mybranch
1204
++* [master^2] Some work.
1205
++* [master^] Some fun.
1206
+------------
1207
+
1208
+Remember, before running `git merge`, our `master` head was at
1209
+"Some fun." commit, while our `mybranch` head was at "Some
1210
+work." commit.
1211
+
1212
+------------
1213
+$ git checkout mybranch
1214
+$ git reset --hard master^2
1215
+$ git checkout master
1216
+$ git reset --hard master^
1217
+------------
1218
+
1219
+After rewinding, the commit structure should look like this:
1220
+
1221
+------------
1222
+$ git show-branch
1223
+* [master] Some fun.
1224
+ ! [mybranch] Some work.
1225
+--
1226
+ + [mybranch] Some work.
1227
+* [master] Some fun.
1228
+*+ [mybranch^] New day.
1229
+------------
1230
+
1231
+Now we are ready to experiment with the merge by hand.
1232
+
1233
+`git merge` command, when merging two branches, uses 3-way merge
1234
+algorithm. First, it finds the common ancestor between them.
1235
+The command it uses is `git-merge-base`:
1236
+
1237
+------------
1238
+$ mb=$(git-merge-base HEAD mybranch)
1239
+------------
1240
+
1241
+The command writes the commit object name of the common ancestor
1242
+to the standard output, so we captured its output to a variable,
1243
+because we will be using it in the next step. BTW, the common
1244
+ancestor commit is the "New day." commit in this case. You can
1245
+tell it by:
1246
+
1247
+------------
1248
+$ git-name-rev $mb
1249
+my-first-tag
1250
+------------
1251
+
1252
+After finding out a common ancestor commit, the second step is
1253
+this:
1254
+
1255
+------------
1256
+$ git-read-tree -m -u $mb HEAD mybranch
1257
+------------
1258
+
1259
+This is the same `git-read-tree` command we have already seen,
1260
+but it takes three trees, unlike previous examples. This reads
1261
+the contents of each tree into different 'stage' in the index
1262
+file (the first tree goes to stage 1, the second stage 2,
1263
+etc.). After reading three trees into three stages, the paths
1264
+that are the same in all three stages are 'collapsed' into stage
1265
+0. Also paths that are the same in two of three stages are
1266
+collapsed into stage 0, taking the SHA1 from either stage 2 or
1267
+stage 3, whichever is different from stage 1 (i.e. only one side
1268
+changed from the common ancestor).
1269
+
1270
+After 'collapsing' operation, paths that are different in three
1271
+trees are left in non-zero stages. At this point, you can
1272
+inspect the index file with this command:
1273
+
1274
+------------
1275
+$ git-ls-files --stage
1276
+100644 7f8b141b65fdcee47321e399a2598a235a032422 0 example
1277
+100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello
1278
+100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello
1279
+100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello
1280
+------------
1281
+
1282
+In our example of only two files, we did not have unchanged
1283
+files so only 'example' resulted in collapsing, but in real-life
1284
+large projects, only small number of files change in one commit,
1285
+and this 'collapsing' tends to trivially merge most of the paths
1286
+fairly quickly, leaving only a handful the real changes in non-zero
1287
+stages.
1288
+
1289
+To look at only non-zero stages, use `\--unmerged` flag:
1290
+
1291
+------------
1292
+$ git-ls-files --unmerged
1293
+100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello
1294
+100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello
1295
+100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello
1296
+------------
1297
+
1298
+The next step of merging is to merge these three versions of the
1299
+file, using 3-way merge. This is done by giving
1300
+`git-merge-one-file` command as one of the arguments to
1301
+`git-merge-index` command:
1302
+
1303
+------------
1304
+$ git-merge-index git-merge-one-file hello
1305
+Auto-merging hello.
1306
+merge: warning: conflicts during merge
1307
+ERROR: Merge conflict in hello.
1308
+fatal: merge program failed
1309
+------------
1310
+
1311
+`git-merge-one-file` script is called with parameters to
1312
+describe those three versions, and is responsible to leave the
1313
+merge results in the working tree.
1314
+It is a fairly straightforward shell script, and
1315
+eventually calls `merge` program from RCS suite to perform a
1316
+file-level 3-way merge. In this case, `merge` detects
1317
+conflicts, and the merge result with conflict marks is left in
1318
+the working tree.. This can be seen if you run `ls-files
1319
+--stage` again at this point:
1320
+
1321
+------------
1322
+$ git-ls-files --stage
1323
+100644 7f8b141b65fdcee47321e399a2598a235a032422 0 example
1324
+100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello
1325
+100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello
1326
+100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello
1327
+------------
1328
+
1329
+This is the state of the index file and the working file after
1330
+`git merge` returns control back to you, leaving the conflicting
1331
+merge for you to resolve. Notice that the path `hello` is still
1332
+unmerged, and what you see with `git diff` at this point is
1333
+differences since stage 2 (i.e. your version).
1334
+
1335
+
1336
+Publishing your work
1337
+--------------------
1338
+
1339
+So we can use somebody else's work from a remote repository; but
1340
+how can *you* prepare a repository to let other people pull from
1341
+it?
1342
+
1343
+Your do your real work in your working tree that has your
1344
+primary repository hanging under it as its `.git` subdirectory.
1345
+You *could* make that repository accessible remotely and ask
1346
+people to pull from it, but in practice that is not the way
1347
+things are usually done. A recommended way is to have a public
1348
+repository, make it reachable by other people, and when the
1349
+changes you made in your primary working tree are in good shape,
1350
+update the public repository from it. This is often called
1351
+'pushing'.
1352
+
1353
+[NOTE]
1354
+This public repository could further be mirrored, and that is
1355
+how git repositories at `kernel.org` are managed.
1356
+
1357
+Publishing the changes from your local (private) repository to
1358
+your remote (public) repository requires a write privilege on
1359
+the remote machine. You need to have an SSH account there to
1360
+run a single command, `git-receive-pack`.
1361
+
1362
+First, you need to create an empty repository on the remote
1363
+machine that will house your public repository. This empty
1364
+repository will be populated and be kept up-to-date by pushing
1365
+into it later. Obviously, this repository creation needs to be
1366
+done only once.
1367
+
1368
+[NOTE]
1369
+`git push` uses a pair of programs,
1370
+`git-send-pack` on your local machine, and `git-receive-pack`
1371
+on the remote machine. The communication between the two over
1372
+the network internally uses an SSH connection.
1373
+
1374
+Your private repository's git directory is usually `.git`, but
1375
+your public repository is often named after the project name,
1376
+i.e. `<project>.git`. Let's create such a public repository for
1377
+project `my-git`. After logging into the remote machine, create
1378
+an empty directory:
1379
+
1380
+------------
1381
+$ mkdir my-git.git
1382
+------------
1383
+
1384
+Then, make that directory into a git repository by running
1385
+`git init-db`, but this time, since its name is not the usual
1386
+`.git`, we do things slightly differently:
1387
+
1388
+------------
1389
+$ GIT_DIR=my-git.git git-init-db
1390
+------------
1391
+
1392
+Make sure this directory is available for others you want your
1393
+changes to be pulled by via the transport of your choice. Also
1394
+you need to make sure that you have the `git-receive-pack`
1395
+program on the `$PATH`.
1396
+
1397
+[NOTE]
1398
+Many installations of sshd do not invoke your shell as the login
1399
+shell when you directly run programs; what this means is that if
1400
+your login shell is `bash`, only `.bashrc` is read and not
1401
+`.bash_profile`. As a workaround, make sure `.bashrc` sets up
1402
+`$PATH` so that you can run `git-receive-pack` program.
1403
+
1404
+[NOTE]
1405
+If you plan to publish this repository to be accessed over http,
1406
+you should do `chmod +x my-git.git/hooks/post-update` at this
1407
+point. This makes sure that every time you push into this
1408
+repository, `git-update-server-info` is run.
1409
+
1410
+Your "public repository" is now ready to accept your changes.
1411
+Come back to the machine you have your private repository. From
1412
+there, run this command:
1413
+
1414
+------------
1415
+$ git push <public-host>:/path/to/my-git.git master
1416
+------------
1417
+
1418
+This synchronizes your public repository to match the named
1419
+branch head (i.e. `master` in this case) and objects reachable
1420
+from them in your current repository.
1421
+
1422
+As a real example, this is how I update my public git
1423
+repository. Kernel.org mirror network takes care of the
1424
+propagation to other publicly visible machines:
1425
+
1426
+------------
1427
+$ git push master.kernel.org:/pub/scm/git/git.git/
1428
+------------
1429
+
1430
+
1431
+Packing your repository
1432
+-----------------------
1433
+
1434
+Earlier, we saw that one file under `.git/objects/??/` directory
1435
+is stored for each git object you create. This representation
1436
+is efficient to create atomically and safely, but
1437
+not so convenient to transport over the network. Since git objects are
1438
+immutable once they are created, there is a way to optimize the
1439
+storage by "packing them together". The command
1440
+
1441
+------------
1442
+$ git repack
1443
+------------
1444
+
1445
+will do it for you. If you followed the tutorial examples, you
1446
+would have accumulated about 17 objects in `.git/objects/??/`
1447
+directories by now. `git repack` tells you how many objects it
1448
+packed, and stores the packed file in `.git/objects/pack`
1449
+directory.
1450
+
1451
+[NOTE]
1452
+You will see two files, `pack-\*.pack` and `pack-\*.idx`,
1453
+in `.git/objects/pack` directory. They are closely related to
1454
+each other, and if you ever copy them by hand to a different
1455
+repository for whatever reason, you should make sure you copy
1456
+them together. The former holds all the data from the objects
1457
+in the pack, and the latter holds the index for random
1458
+access.
1459
+
1460
+If you are paranoid, running `git-verify-pack` command would
1461
+detect if you have a corrupt pack, but do not worry too much.
1462
+Our programs are always perfect ;-).
1463
+
1464
+Once you have packed objects, you do not need to leave the
1465
+unpacked objects that are contained in the pack file anymore.
1466
+
1467
+------------
1468
+$ git prune-packed
1469
+------------
1470
+
1471
+would remove them for you.
1472
+
1473
+You can try running `find .git/objects -type f` before and after
1474
+you run `git prune-packed` if you are curious. Also `git
1475
+count-objects` would tell you how many unpacked objects are in
1476
+your repository and how much space they are consuming.
1477
+
1478
+[NOTE]
1479
+`git pull` is slightly cumbersome for HTTP transport, as a
1480
+packed repository may contain relatively few objects in a
1481
+relatively large pack. If you expect many HTTP pulls from your
1482
+public repository you might want to repack & prune often, or
1483
+never.
1484
+
1485
+If you run `git repack` again at this point, it will say
1486
+"Nothing to pack". Once you continue your development and
1487
+accumulate the changes, running `git repack` again will create a
1488
+new pack, that contains objects created since you packed your
1489
+repository the last time. We recommend that you pack your project
1490
+soon after the initial import (unless you are starting your
1491
+project from scratch), and then run `git repack` every once in a
1492
+while, depending on how active your project is.
1493
+
1494
+When a repository is synchronized via `git push` and `git pull`
1495
+objects packed in the source repository are usually stored
1496
+unpacked in the destination, unless rsync transport is used.
1497
+While this allows you to use different packing strategies on
1498
+both ends, it also means you may need to repack both
1499
+repositories every once in a while.
1500
+
1501
+
1502
+Working with Others
1503
+-------------------
1504
+
1505
+Although git is a truly distributed system, it is often
1506
+convenient to organize your project with an informal hierarchy
1507
+of developers. Linux kernel development is run this way. There
1508
+is a nice illustration (page 17, "Merges to Mainline") in Randy
1509
+Dunlap's presentation (`http://tinyurl.com/a2jdg`).
1510
+
1511
+It should be stressed that this hierarchy is purely *informal*.
1512
+There is nothing fundamental in git that enforces the "chain of
1513
+patch flow" this hierarchy implies. You do not have to pull
1514
+from only one remote repository.
1515
+
1516
+A recommended workflow for a "project lead" goes like this:
1517
+
1518
+1. Prepare your primary repository on your local machine. Your
1519
+ work is done there.
1520
+
1521
+2. Prepare a public repository accessible to others.
1522
++
1523
+If other people are pulling from your repository over dumb
1524
+transport protocols (HTTP), you need to keep this repository
1525
+'dumb transport friendly'. After `git init-db`,
1526
+`$GIT_DIR/hooks/post-update` copied from the standard templates
1527
+would contain a call to `git-update-server-info` but the
1528
+`post-update` hook itself is disabled by default -- enable it
1529
+with `chmod +x post-update`. This makes sure `git-update-server-info`
1530
+keeps the necessary files up-to-date.
1531
+
1532
+3. Push into the public repository from your primary
1533
+ repository.
1534
+
1535
+4. `git repack` the public repository. This establishes a big
1536
+ pack that contains the initial set of objects as the
1537
+ baseline, and possibly `git prune` if the transport
1538
+ used for pulling from your repository supports packed
1539
+ repositories.
1540
+
1541
+5. Keep working in your primary repository. Your changes
1542
+ include modifications of your own, patches you receive via
1543
+ e-mails, and merges resulting from pulling the "public"
1544
+ repositories of your "subsystem maintainers".
1545
++
1546
+You can repack this private repository whenever you feel like.
1547
+
1548
+6. Push your changes to the public repository, and announce it
1549
+ to the public.
1550
+
1551
+7. Every once in a while, "git repack" the public repository.
1552
+ Go back to step 5. and continue working.
1553
+
1554
+
1555
+A recommended work cycle for a "subsystem maintainer" who works
1556
+on that project and has an own "public repository" goes like this:
1557
+
1558
+1. Prepare your work repository, by `git clone` the public
1559
+ repository of the "project lead". The URL used for the
1560
+ initial cloning is stored in `.git/remotes/origin`.
1561
+
1562
+2. Prepare a public repository accessible to others, just like
1563
+ the "project lead" person does.
1564
+
1565
+3. Copy over the packed files from "project lead" public
1566
+ repository to your public repository, unless the "project
1567
+ lead" repository lives on the same machine as yours. In the
1568
+ latter case, you can use `objects/info/alternates` file to
1569
+ point at the repository you are borrowing from.
1570
+
1571
+4. Push into the public repository from your primary
1572
+ repository. Run `git repack`, and possibly `git prune` if the
1573
+ transport used for pulling from your repository supports
1574
+ packed repositories.
1575
+
1576
+5. Keep working in your primary repository. Your changes
1577
+ include modifications of your own, patches you receive via
1578
+ e-mails, and merges resulting from pulling the "public"
1579
+ repositories of your "project lead" and possibly your
1580
+ "sub-subsystem maintainers".
1581
++
1582
+You can repack this private repository whenever you feel
1583
+like.
1584
+
1585
+6. Push your changes to your public repository, and ask your
1586
+ "project lead" and possibly your "sub-subsystem
1587
+ maintainers" to pull from it.
1588
+
1589
+7. Every once in a while, `git repack` the public repository.
1590
+ Go back to step 5. and continue working.
1591
+
1592
+
1593
+A recommended work cycle for an "individual developer" who does
1594
+not have a "public" repository is somewhat different. It goes
1595
+like this:
1596
+
1597
+1. Prepare your work repository, by `git clone` the public
1598
+ repository of the "project lead" (or a "subsystem
1599
+ maintainer", if you work on a subsystem). The URL used for
1600
+ the initial cloning is stored in `.git/remotes/origin`.
1601
+
1602
+2. Do your work in your repository on 'master' branch.
1603
+
1604
+3. Run `git fetch origin` from the public repository of your
1605
+ upstream every once in a while. This does only the first
1606
+ half of `git pull` but does not merge. The head of the
1607
+ public repository is stored in `.git/refs/heads/origin`.
1608
+
1609
+4. Use `git cherry origin` to see which ones of your patches
1610
+ were accepted, and/or use `git rebase origin` to port your
1611
+ unmerged changes forward to the updated upstream.
1612
+
1613
+5. Use `git format-patch origin` to prepare patches for e-mail
1614
+ submission to your upstream and send it out. Go back to
1615
+ step 2. and continue.
1616
+
1617
+
1618
+Working with Others, Shared Repository Style
1619
+--------------------------------------------
1620
+
1621
+If you are coming from CVS background, the style of cooperation
1622
+suggested in the previous section may be new to you. You do not
1623
+have to worry. git supports "shared public repository" style of
1624
+cooperation you are probably more familiar with as well.
1625
+
1626
+For this, set up a public repository on a machine that is
1627
+reachable via SSH by people with "commit privileges". Put the
1628
+committers in the same user group and make the repository
1629
+writable by that group. Make sure their umasks are set up to
1630
+allow group members to write into directories other members
1631
+have created.
1632
+
1633
+You, as an individual committer, then:
1634
+
1635
+- First clone the shared repository to a local repository:
1636
+------------------------------------------------
1637
+$ git clone repo.shared.xz:/pub/scm/project.git/ my-project
1638
+$ cd my-project
1639
+$ hack away
1640
+------------------------------------------------
1641
+
1642
+- Merge the work others might have done while you were hacking
1643
+ away:
1644
+------------------------------------------------
1645
+$ git pull origin
1646
+$ test the merge result
1647
+------------------------------------------------
1648
+[NOTE]
1649
+================================
1650
+The first `git clone` would have placed the following in
1651
+`my-project/.git/remotes/origin` file, and that's why this and
1652
+the next step work.
1653
+------------
1654
+URL: repo.shared.xz:/pub/scm/project.git/ my-project
1655
+Pull: master:origin
1656
+------------
1657
+================================
1658
+
1659
+- push your work as the new head of the shared
1660
+ repository.
1661
+------------------------------------------------
1662
+$ git push origin master
1663
+------------------------------------------------
1664
+If somebody else pushed into the same shared repository while
1665
+you were working locally, `git push` in the last step would
1666
+complain, telling you that the remote `master` head does not
1667
+fast forward. You need to pull and merge those other changes
1668
+back before you push your work when it happens.
1669
+
1670
+
1671
+Advanced Shared Repository Management
1672
+-------------------------------------
1673
+
1674
+Being able to push into a shared repository means being able to
1675
+write into it. If your developers are coming over the network,
1676
+this means you, as the repository administrator, need to give
1677
+each of them an SSH access to the shared repository machine.
1678
+
1679
+In some cases, though, you may not want to give a normal shell
1680
+account to them, but want to restrict them to be able to only
1681
+do `git push` into the repository and nothing else.
1682
+
1683
+You can achieve this by setting the login shell of your
1684
+developers on the shared repository host to `git-shell` program.
1685
+
1686
+[NOTE]
1687
+Most likely you would also need to list `git-shell` program in
1688
+`/etc/shells` file.
1689
+
1690
+This restricts the set of commands that can be run from incoming
1691
+SSH connection for these users to only `receive-pack` and
1692
+`upload-pack`, so the only thing they can do are `git fetch` and
1693
+`git push`.
1694
+
1695
+You still need to create UNIX user accounts for each developer,
1696
+and put them in the same group. Make sure that the repository
1697
+shared among these developers is writable by that group.
1698
+
1699
+. Initializing the shared repository with `git-init-db --shared`
1700
+helps somewhat.
1701
+
1702
+. Run the following in the shared repository:
1703
++
1704
+------------
1705
+$ chgrp -R $group repo.git
1706
+$ find repo.git -type d -print | xargs chmod ug+rwx,g+s
1707
+$ GIT_DIR=repo.git git repo-config core.sharedrepository true
1708
+------------
1709
+
1710
+The above measures make sure that directories lazily created in
1711
+`$GIT_DIR` are writable by group members. You, as the
1712
+repository administrator, are still responsible to make sure
1713
+your developers belong to that shared repository group and set
1714
+their umask to a value no stricter than 027 (i.e. at least allow
1715
+reading and searching by group members).
1716
+
1717
+You can implement finer grained branch policies using update
1718
+hooks. There is a document ("control access to branches") in
1719
+Documentation/howto by Carl Baldwin and JC outlining how to (1)
1720
+limit access to branch per user, (2) forbid overwriting existing
1721
+tags.
1722
+
1723
+
1724
+Bundling your work together
1725
+---------------------------
1726
+
1727
+It is likely that you will be working on more than one thing at
1728
+a time. It is easy to manage those more-or-less independent tasks
1729
+using branches with git.
1730
+
1731
+We have already seen how branches work previously,
1732
+with "fun and work" example using two branches. The idea is the
1733
+same if there are more than two branches. Let's say you started
1734
+out from "master" head, and have some new code in the "master"
1735
+branch, and two independent fixes in the "commit-fix" and
1736
+"diff-fix" branches:
1737
+
1738
+------------
1739
+$ git show-branch
1740
+! [commit-fix] Fix commit message normalization.
1741
+ ! [diff-fix] Fix rename detection.
1742
+ * [master] Release candidate #1
1743
+---
1744
+ + [diff-fix] Fix rename detection.
1745
+ + [diff-fix~1] Better common substring algorithm.
1746
++ [commit-fix] Fix commit message normalization.
1747
+ * [master] Release candidate #1
1748
+++* [diff-fix~2] Pretty-print messages.
1749
+------------
1750
+
1751
+Both fixes are tested well, and at this point, you want to merge
1752
+in both of them. You could merge in 'diff-fix' first and then
1753
+'commit-fix' next, like this:
1754
+
1755
+------------
1756
+$ git merge 'Merge fix in diff-fix' master diff-fix
1757
+$ git merge 'Merge fix in commit-fix' master commit-fix
1758
+------------
1759
+
1760
+Which would result in:
1761
+
1762
+------------
1763
+$ git show-branch
1764
+! [commit-fix] Fix commit message normalization.
1765
+ ! [diff-fix] Fix rename detection.
1766
+ * [master] Merge fix in commit-fix
1767
+---
1768
+ - [master] Merge fix in commit-fix
1769
++ * [commit-fix] Fix commit message normalization.
1770
+ - [master~1] Merge fix in diff-fix
1771
+ +* [diff-fix] Fix rename detection.
1772
+ +* [diff-fix~1] Better common substring algorithm.
1773
+ * [master~2] Release candidate #1
1774
+++* [master~3] Pretty-print messages.
1775
+------------
1776
+
1777
+However, there is no particular reason to merge in one branch
1778
+first and the other next, when what you have are a set of truly
1779
+independent changes (if the order mattered, then they are not
1780
+independent by definition). You could instead merge those two
1781
+branches into the current branch at once. First let's undo what
1782
+we just did and start over. We would want to get the master
1783
+branch before these two merges by resetting it to 'master~2':
1784
+
1785
+------------
1786
+$ git reset --hard master~2
1787
+------------
1788
+
1789
+You can make sure 'git show-branch' matches the state before
1790
+those two 'git merge' you just did. Then, instead of running
1791
+two 'git merge' commands in a row, you would pull these two
1792
+branch heads (this is known as 'making an Octopus'):
1793
+
1794
+------------
1795
+$ git pull . commit-fix diff-fix
1796
+$ git show-branch
1797
+! [commit-fix] Fix commit message normalization.
1798
+ ! [diff-fix] Fix rename detection.
1799
+ * [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
1800
+---
1801
+ - [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
1802
++ * [commit-fix] Fix commit message normalization.
1803
+ +* [diff-fix] Fix rename detection.
1804
+ +* [diff-fix~1] Better common substring algorithm.
1805
+ * [master~1] Release candidate #1
1806
+++* [master~2] Pretty-print messages.
1807
+------------
1808
+
1809
+Note that you should not do Octopus because you can. An octopus
1810
+is a valid thing to do and often makes it easier to view the
1811
+commit history if you are pulling more than two independent
1812
+changes at the same time. However, if you have merge conflicts
1813
+with any of the branches you are merging in and need to hand
1814
+resolve, that is an indication that the development happened in
1815
+those branches were not independent after all, and you should
1816
+merge two at a time, documenting how you resolved the conflicts,
1817
+and the reason why you preferred changes made in one side over
1818
+the other. Otherwise it would make the project history harder
1819
+to follow, not easier.
1820
+
1821
+[ to be continued.. cvsimports ]
Documentation/tutorial.txt
renamed
+286
-1701
@@ -1,1821 +1,404 @@
1
-A short git tutorial
2
-====================
1
+A tutorial introduction to git
2
+==============================
3
4
-Introduction
5
-------------
4
+This tutorial explains how to import a new project into git, make
5
+changes to it, and share changes with other developers.
6
7
-This is trying to be a short tutorial on setting up and using a git
8
-repository, mainly because being hands-on and using explicit examples is
9
-often the best way of explaining what is going on.
7
+First, note that you can get documentation for a command such as "git
8
+diff" with:
9
11
-In normal life, most people wouldn't use the "core" git programs
12
-directly, but rather script around them to make them more palatable.
13
-Understanding the core git stuff may help some people get those scripts
14
-done, though, and it may also be instructive in helping people
15
-understand what it is that the higher-level helper scripts are actually
16
-doing.
17
-
18
-The core git is often called "plumbing", with the prettier user
19
-interfaces on top of it called "porcelain". You may not want to use the
20
-plumbing directly very often, but it can be good to know what the
21
-plumbing does for when the porcelain isn't flushing.
22
-
23
-The material presented here often goes deep describing how things
24
-work internally. If you are mostly interested in using git as a
25
-SCM, you can skip them during your first pass.
26
-
27
-[NOTE]
28
-And those "too deep" descriptions are often marked as Note.
29
-
30
-[NOTE]
31
-If you are already familiar with another version control system,
32
-like CVS, you may want to take a look at
33
-link:everyday.html[Everyday GIT in 20 commands or so] first
34
-before reading this.
35
-
36
-
37
-Creating a git repository
38
--------------------------
10
+------------------------------------------------
11
+$ man git-diff
12
+------------------------------------------------
13
40
-Creating a new git repository couldn't be easier: all git repositories start
41
-out empty, and the only thing you need to do is find yourself a
42
-subdirectory that you want to use as a working tree - either an empty
43
-one for a totally new project, or an existing working tree that you want
44
-to import into git.
14
+Importing a new project
15
+-----------------------
16
46
-For our first example, we're going to start a totally new repository from
47
-scratch, with no pre-existing files, and we'll call it `git-tutorial`.
48
-To start up, create a subdirectory for it, change into that
49
-subdirectory, and initialize the git infrastructure with `git-init-db`:
17
+Assume you have a tarball project.tar.gz with your initial work. You
18
+can place it under git revision control as follows.
19
20
------------------------------------------------
52
-$ mkdir git-tutorial
53
-$ cd git-tutorial
54
-$ git-init-db
21
+$ tar -xzf project.tar.gz
22
+$ cd project
23
+$ git init-db
24
------------------------------------------------
25
57
-to which git will reply
26
+Git will reply
27
59
-----------------
28
+------------------------------------------------
29
defaulting to local storage area
61
-----------------
62
-
63
-which is just git's way of saying that you haven't been doing anything
64
-strange, and that it will have created a local `.git` directory setup for
65
-your new project. You will now have a `.git` directory, and you can
66
-inspect that with `ls`. For your new empty project, it should show you
67
-three entries, among other things:
68
-
69
- - a symlink called `HEAD`, pointing to `refs/heads/master` (if your
70
- platform does not have native symlinks, it is a file containing the
71
- line "ref: refs/heads/master")
72
-+
73
-Don't worry about the fact that the file that the `HEAD` link points to
74
-doesn't even exist yet -- you haven't created the commit that will
75
-start your `HEAD` development branch yet.
76
-
77
- - a subdirectory called `objects`, which will contain all the
78
- objects of your project. You should never have any real reason to
79
- look at the objects directly, but you might want to know that these
80
- objects are what contains all the real 'data' in your repository.
81
-
82
- - a subdirectory called `refs`, which contains references to objects.
83
-
84
-In particular, the `refs` subdirectory will contain two other
85
-subdirectories, named `heads` and `tags` respectively. They do
86
-exactly what their names imply: they contain references to any number
87
-of different 'heads' of development (aka 'branches'), and to any
88
-'tags' that you have created to name specific versions in your
89
-repository.
90
-
91
-One note: the special `master` head is the default branch, which is
92
-why the `.git/HEAD` file was created as a symlink to it even if it
93
-doesn't yet exist. Basically, the `HEAD` link is supposed to always
94
-point to the branch you are working on right now, and you always
95
-start out expecting to work on the `master` branch.
96
-
97
-However, this is only a convention, and you can name your branches
98
-anything you want, and don't have to ever even 'have' a `master`
99
-branch. A number of the git tools will assume that `.git/HEAD` is
100
-valid, though.
101
-
102
-[NOTE]
103
-An 'object' is identified by its 160-bit SHA1 hash, aka 'object name',
104
-and a reference to an object is always the 40-byte hex
105
-representation of that SHA1 name. The files in the `refs`
106
-subdirectory are expected to contain these hex references
107
-(usually with a final `\'\n\'` at the end), and you should thus
108
-expect to see a number of 41-byte files containing these
109
-references in these `refs` subdirectories when you actually start
110
-populating your tree.
111
-
112
-[NOTE]
113
-An advanced user may want to take a look at the
114
-link:repository-layout.html[repository layout] document
115
-after finishing this tutorial.
116
-
117
-You have now created your first git repository. Of course, since it's
118
-empty, that's not very useful, so let's start populating it with data.
119
-
120
-
121
-Populating a git repository
122
----------------------------
123
-
124
-We'll keep this simple and stupid, so we'll start off with populating a
125
-few trivial files just to get a feel for it.
30
+------------------------------------------------
31
127
-Start off with just creating any random files that you want to maintain
128
-in your git repository. We'll start off with a few bad examples, just to
129
-get a feel for how this works:
32
+You've now initialized the working directory--you may notice a new
33
+directory created, named ".git". Tell git that you want it to track
34
+every file under the current directory with
35
36
------------------------------------------------
132
-$ echo "Hello World" >hello
133
-$ echo "Silly example" >example
37
+$ git add .
38
------------------------------------------------
39
136
-you have now created two files in your working tree (aka 'working directory'), but to
137
-actually check in your hard work, you will have to go through two steps:
138
-
139
- - fill in the 'index' file (aka 'cache') with the information about your
140
- working tree state.
40
+Finally,
41
142
- - commit that index file as an object.
42
+------------------------------------------------
43
+$ git commit -a
44
+------------------------------------------------
45
144
-The first step is trivial: when you want to tell git about any changes
145
-to your working tree, you use the `git-update-index` program. That
146
-program normally just takes a list of filenames you want to update, but
147
-to avoid trivial mistakes, it refuses to add new entries to the index
148
-(or remove existing ones) unless you explicitly tell it that you're
149
-adding a new entry with the `\--add` flag (or removing an entry with the
150
-`\--remove`) flag.
46
+will prompt you for a commit message, then record the current state
47
+of all the files to the repository.
48
152
-So to populate the index with the two files you just created, you can do
49
+Try modifying some files, then run
50
51
------------------------------------------------
155
-$ git-update-index --add hello example
52
+$ git diff
53
------------------------------------------------
54
158
-and you have now told git to track those two files.
159
-
160
-In fact, as you did that, if you now look into your object directory,
161
-you'll notice that git will have added two new objects to the object
162
-database. If you did exactly the steps above, you should now be able to do
55
+to review your changes. When you're done,
56
57
+------------------------------------------------
58
+$ git commit -a
59
+------------------------------------------------
60
165
-----------------
166
-$ ls .git/objects/??/*
167
-----------------
61
+will again prompt your for a message describing the change, and then
62
+record the new versions of the modified files.
63
169
-and see two files:
64
+A note on commit messages: Though not required, it's a good idea to
65
+begin the commit message with a single short (less than 50 character)
66
+line summarizing the change, followed by a blank line and then a more
67
+thorough description. Tools that turn commits into email, for
68
+example, use the first line on the Subject line and the rest of the
69
+commit in the body.
70
171
-----------------
172
-.git/objects/55/7db03de997c86a4a028e1ebd3a1ceb225be238
173
-.git/objects/f2/4c74a2e500f5ee1332c86b94199f52b1d1d962
174
-----------------
71
+To add a new file, first create the file, then
72
176
-which correspond with the objects with names of 557db... and f24c7..
177
-respectively.
73
+------------------------------------------------
74
+$ git add path/to/new/file
75
+------------------------------------------------
76
179
-If you want to, you can use `git-cat-file` to look at those objects, but
180
-you'll have to use the object name, not the filename of the object:
77
+then commit as usual. No special command is required when removing a
78
+file; just remove it, then commit.
79
182
-----------------
183
-$ git-cat-file -t 557db03de997c86a4a028e1ebd3a1ceb225be238
184
-----------------
80
+At any point you can view the history of your changes using
81
186
-where the `-t` tells `git-cat-file` to tell you what the "type" of the
187
-object is. git will tell you that you have a "blob" object (ie just a
188
-regular file), and you can see the contents with
82
+------------------------------------------------
83
+$ git whatchanged
84
+------------------------------------------------
85
190
-----------------
191
-$ git-cat-file "blob" 557db03
192
-----------------
86
+If you also want to see complete diffs at each step, use
87
194
-which will print out "Hello World". The object 557db03 is nothing
195
-more than the contents of your file `hello`.
88
+------------------------------------------------
89
+$ git whatchanged -p
90
+------------------------------------------------
91
197
-[NOTE]
198
-Don't confuse that object with the file `hello` itself. The
199
-object is literally just those specific *contents* of the file, and
200
-however much you later change the contents in file `hello`, the object
201
-we just looked at will never change. Objects are immutable.
92
+Managing branches
93
+-----------------
94
203
-[NOTE]
204
-The second example demonstrates that you can
205
-abbreviate the object name to only the first several
206
-hexadecimal digits in most places.
95
+A single git repository can maintain multiple branches of
96
+development. To create a new branch named "experimental", use
97
208
-Anyway, as we mentioned previously, you normally never actually take a
209
-look at the objects themselves, and typing long 40-character hex
210
-names is not something you'd normally want to do. The above digression
211
-was just to show that `git-update-index` did something magical, and
212
-actually saved away the contents of your files into the git object
213
-database.
98
+------------------------------------------------
99
+$ git branch experimental
100
+------------------------------------------------
101
215
-Updating the index did something else too: it created a `.git/index`
216
-file. This is the index that describes your current working tree, and
217
-something you should be very aware of. Again, you normally never worry
218
-about the index file itself, but you should be aware of the fact that
219
-you have not actually really "checked in" your files into git so far,
220
-you've only *told* git about them.
102
+If you now run
103
222
-However, since git knows about them, you can now start using some of the
223
-most basic git commands to manipulate the files or look at their status.
104
+------------------------------------------------
105
+$ git branch
106
+------------------------------------------------
107
225
-In particular, let's not even check in the two files into git yet, we'll
226
-start off by adding another line to `hello` first:
108
+you'll get a list of all existing branches:
109
110
------------------------------------------------
229
-$ echo "It's a new day for git" >>hello
111
+ experimental
112
+* master
113
------------------------------------------------
114
232
-and you can now, since you told git about the previous state of `hello`, ask
233
-git what has changed in the tree compared to your old index, using the
234
-`git-diff-files` command:
115
+The "experimental" branch is the one you just created, and the
116
+"master" branch is a default branch that was created for you
117
+automatically. The asterisk marks the branch you are currently on;
118
+type
119
236
-------------
237
-$ git-diff-files
238
-------------
120
+------------------------------------------------
121
+$ git checkout experimental
122
+------------------------------------------------
123
240
-Oops. That wasn't very readable. It just spit out its own internal
241
-version of a `diff`, but that internal version really just tells you
242
-that it has noticed that "hello" has been modified, and that the old object
243
-contents it had have been replaced with something else.
124
+to switch to the experimental branch. Now edit a file, commit the
125
+change, and switch back to the master branch:
126
245
-To make it readable, we can tell git-diff-files to output the
246
-differences as a patch, using the `-p` flag:
127
+------------------------------------------------
128
+(edit file)
129
+$ git commit -a
130
+$ git checkout master
131
+------------------------------------------------
132
248
-------------
249
-$ git-diff-files -p
250
-diff --git a/hello b/hello
251
-index 557db03..263414f 100644
252
---- a/hello
253
-+++ b/hello
254
-@@ -1 +1,2 @@
255
- Hello World
256
-+It's a new day for git
257
-----
133
+Check that the change you made is no longer visible, since it was
134
+made on the experimental branch and you're back on the master branch.
135
259
-i.e. the diff of the change we caused by adding another line to `hello`.
136
+You can make a different change on the master branch:
137
261
-In other words, `git-diff-files` always shows us the difference between
262
-what is recorded in the index, and what is currently in the working
263
-tree. That's very useful.
138
+------------------------------------------------
139
+(edit file)
140
+$ git commit -a
141
+------------------------------------------------
142
265
-A common shorthand for `git-diff-files -p` is to just write `git
266
-diff`, which will do the same thing.
143
+at this point the two branches have diverged, with different changes
144
+made in each. To merge the changes made in the two branches, run
145
268
-------------
269
-$ git diff
270
-diff --git a/hello b/hello
271
-index 557db03..263414f 100644
272
---- a/hello
273
-+++ b/hello
274
-@@ -1 +1,2 @@
275
- Hello World
276
-+It's a new day for git
277
-------------
278
-
279
-
280
-Committing git state
281
---------------------
282
-
283
-Now, we want to go to the next stage in git, which is to take the files
284
-that git knows about in the index, and commit them as a real tree. We do
285
-that in two phases: creating a 'tree' object, and committing that 'tree'
286
-object as a 'commit' object together with an explanation of what the
287
-tree was all about, along with information of how we came to that state.
288
-
289
-Creating a tree object is trivial, and is done with `git-write-tree`.
290
-There are no options or other input: git-write-tree will take the
291
-current index state, and write an object that describes that whole
292
-index. In other words, we're now tying together all the different
293
-filenames with their contents (and their permissions), and we're
294
-creating the equivalent of a git "directory" object:
146
+------------------------------------------------
147
+$ git pull . experimental
148
+------------------------------------------------
149
+
150
+If the changes don't conflict, you're done. If there are conflicts,
151
+markers will be left in the problematic files showing the conflict;
152
153
------------------------------------------------
297
-$ git-write-tree
154
+$ git diff
155
------------------------------------------------
156
300
-and this will just output the name of the resulting tree, in this case
301
-(if you have done exactly as I've described) it should be
302
-
303
-----------------
304
-8988da15d077d4829fc51d8544c097def6644dbb
305
-----------------
306
-
307
-which is another incomprehensible object name. Again, if you want to,
308
-you can use `git-cat-file -t 8988d\...` to see that this time the object
309
-is not a "blob" object, but a "tree" object (you can also use
310
-`git-cat-file` to actually output the raw object contents, but you'll see
311
-mainly a binary mess, so that's less interesting).
312
-
313
-However -- normally you'd never use `git-write-tree` on its own, because
314
-normally you always commit a tree into a commit object using the
315
-`git-commit-tree` command. In fact, it's easier to not actually use
316
-`git-write-tree` on its own at all, but to just pass its result in as an
317
-argument to `git-commit-tree`.
318
-
319
-`git-commit-tree` normally takes several arguments -- it wants to know
320
-what the 'parent' of a commit was, but since this is the first commit
321
-ever in this new repository, and it has no parents, we only need to pass in
322
-the object name of the tree. However, `git-commit-tree`
323
-also wants to get a commit message
324
-on its standard input, and it will write out the resulting object name for the
325
-commit to its standard output.
326
-
327
-And this is where we create the `.git/refs/heads/master` file
328
-which is pointed at by `HEAD`. This file is supposed to contain
329
-the reference to the top-of-tree of the master branch, and since
330
-that's exactly what `git-commit-tree` spits out, we can do this
331
-all with a sequence of simple shell commands:
157
+will show this. Once you've edited the files to resolve the
158
+conflicts,
159
160
------------------------------------------------
334
-$ tree=$(git-write-tree)
335
-$ commit=$(echo 'Initial commit' | git-commit-tree $tree)
336
-$ git-update-ref HEAD $commit
161
+$ git commit -a
162
------------------------------------------------
163
339
-which will say:
340
-
341
-----------------
342
-Committing initial tree 8988da15d077d4829fc51d8544c097def6644dbb
343
-----------------
344
-
345
-just to warn you about the fact that it created a totally new commit
346
-that is not related to anything else. Normally you do this only *once*
347
-for a project ever, and all later commits will be parented on top of an
348
-earlier commit, and you'll never see this "Committing initial tree"
349
-message ever again.
350
-
351
-Again, normally you'd never actually do this by hand. There is a
352
-helpful script called `git commit` that will do all of this for you. So
353
-you could have just written `git commit`
354
-instead, and it would have done the above magic scripting for you.
355
-
356
-
357
-Making a change
358
----------------
359
-
360
-Remember how we did the `git-update-index` on file `hello` and then we
361
-changed `hello` afterward, and could compare the new state of `hello` with the
362
-state we saved in the index file?
363
-
364
-Further, remember how I said that `git-write-tree` writes the contents
365
-of the *index* file to the tree, and thus what we just committed was in
366
-fact the *original* contents of the file `hello`, not the new ones. We did
367
-that on purpose, to show the difference between the index state, and the
368
-state in the working tree, and how they don't have to match, even
369
-when we commit things.
370
-
371
-As before, if we do `git-diff-files -p` in our git-tutorial project,
372
-we'll still see the same difference we saw last time: the index file
373
-hasn't changed by the act of committing anything. However, now that we
374
-have committed something, we can also learn to use a new command:
375
-`git-diff-index`.
376
-
377
-Unlike `git-diff-files`, which showed the difference between the index
378
-file and the working tree, `git-diff-index` shows the differences
379
-between a committed *tree* and either the index file or the working
380
-tree. In other words, `git-diff-index` wants a tree to be diffed
381
-against, and before we did the commit, we couldn't do that, because we
382
-didn't have anything to diff against.
383
-
384
-But now we can do
385
-
386
-----------------
387
-$ git-diff-index -p HEAD
388
-----------------
389
-
390
-(where `-p` has the same meaning as it did in `git-diff-files`), and it
391
-will show us the same difference, but for a totally different reason.
392
-Now we're comparing the working tree not against the index file,
393
-but against the tree we just wrote. It just so happens that those two
394
-are obviously the same, so we get the same result.
395
-
396
-Again, because this is a common operation, you can also just shorthand
397
-it with
398
-
399
-----------------
400
-$ git diff HEAD
401
-----------------
402
-
403
-which ends up doing the above for you.
404
-
405
-In other words, `git-diff-index` normally compares a tree against the
406
-working tree, but when given the `\--cached` flag, it is told to
407
-instead compare against just the index cache contents, and ignore the
408
-current working tree state entirely. Since we just wrote the index
409
-file to HEAD, doing `git-diff-index \--cached -p HEAD` should thus return
410
-an empty set of differences, and that's exactly what it does.
411
-
412
-[NOTE]
413
-================
414
-`git-diff-index` really always uses the index for its
415
-comparisons, and saying that it compares a tree against the working
416
-tree is thus not strictly accurate. In particular, the list of
417
-files to compare (the "meta-data") *always* comes from the index file,
418
-regardless of whether the `\--cached` flag is used or not. The `\--cached`
419
-flag really only determines whether the file *contents* to be compared
420
-come from the working tree or not.
421
-
422
-This is not hard to understand, as soon as you realize that git simply
423
-never knows (or cares) about files that it is not told about
424
-explicitly. git will never go *looking* for files to compare, it
425
-expects you to tell it what the files are, and that's what the index
426
-is there for.
427
-================
428
-
429
-However, our next step is to commit the *change* we did, and again, to
430
-understand what's going on, keep in mind the difference between "working
431
-tree contents", "index file" and "committed tree". We have changes
432
-in the working tree that we want to commit, and we always have to
433
-work through the index file, so the first thing we need to do is to
434
-update the index cache:
164
+will commit the result of the merge. Finally,
165
166
------------------------------------------------
437
-$ git-update-index hello
167
+$ gitk
168
------------------------------------------------
169
440
-(note how we didn't need the `\--add` flag this time, since git knew
441
-about the file already).
170
+will show a nice graphical representation of the resulting history.
171
443
-Note what happens to the different `git-diff-\*` versions here. After
444
-we've updated `hello` in the index, `git-diff-files -p` now shows no
445
-differences, but `git-diff-index -p HEAD` still *does* show that the
446
-current state is different from the state we committed. In fact, now
447
-`git-diff-index` shows the same difference whether we use the `--cached`
448
-flag or not, since now the index is coherent with the working tree.
172
+If you develop on a branch crazy-idea, then regret it, you can always
173
+delete the branch with
174
450
-Now, since we've updated `hello` in the index, we can commit the new
451
-version. We could do it by writing the tree by hand again, and
452
-committing the tree (this time we'd have to use the `-p HEAD` flag to
453
-tell commit that the HEAD was the *parent* of the new commit, and that
454
-this wasn't an initial commit any more), but you've done that once
455
-already, so let's just use the helpful script this time:
175
+-------------------------------------
176
+$ git branch -D crazy-idea
177
+-------------------------------------
178
457
-------------------------------------------------
458
-$ git commit
459
-------------------------------------------------
179
+Branches are cheap and easy, so this is a good way to try something
180
+out.
181
461
-which starts an editor for you to write the commit message and tells you
462
-a bit about what you have done.
463
-
464
-Write whatever message you want, and all the lines that start with '#'
465
-will be pruned out, and the rest will be used as the commit message for
466
-the change. If you decide you don't want to commit anything after all at
467
-this point (you can continue to edit things and update the index), you
468
-can just leave an empty message. Otherwise `git commit` will commit
469
-the change for you.
470
-
471
-You've now made your first real git commit. And if you're interested in
472
-looking at what `git commit` really does, feel free to investigate:
473
-it's a few very simple shell scripts to generate the helpful (?) commit
474
-message headers, and a few one-liners that actually do the
475
-commit itself (`git-commit`).
476
-
477
-
478
-Inspecting Changes
479
-------------------
480
-
481
-While creating changes is useful, it's even more useful if you can tell
482
-later what changed. The most useful command for this is another of the
483
-`diff` family, namely `git-diff-tree`.
484
-
485
-`git-diff-tree` can be given two arbitrary trees, and it will tell you the
486
-differences between them. Perhaps even more commonly, though, you can
487
-give it just a single commit object, and it will figure out the parent
488
-of that commit itself, and show the difference directly. Thus, to get
489
-the same diff that we've already seen several times, we can now do
490
-
491
-----------------
492
-$ git-diff-tree -p HEAD
493
-----------------
494
-
495
-(again, `-p` means to show the difference as a human-readable patch),
496
-and it will show what the last commit (in `HEAD`) actually changed.
497
-
498
-[NOTE]
499
-============
500
-Here is an ASCII art by Jon Loeliger that illustrates how
501
-various diff-\* commands compare things.
502
-
503
- diff-tree
504
- +----+
505
- | |
506
- | |
507
- V V
508
- +-----------+
509
- | Object DB |
510
- | Backing |
511
- | Store |
512
- +-----------+
513
- ^ ^
514
- | |
515
- | | diff-index --cached
516
- | |
517
- diff-index | V
518
- | +-----------+
519
- | | Index |
520
- | | "cache" |
521
- | +-----------+
522
- | ^
523
- | |
524
- | | diff-files
525
- | |
526
- V V
527
- +-----------+
528
- | Working |
529
- | Directory |
530
- +-----------+
531
-============
532
-
533
-More interestingly, you can also give `git-diff-tree` the `-v` flag, which
534
-tells it to also show the commit message and author and date of the
535
-commit, and you can tell it to show a whole series of diffs.
536
-Alternatively, you can tell it to be "silent", and not show the diffs at
537
-all, but just show the actual commit message.
538
-
539
-In fact, together with the `git-rev-list` program (which generates a
540
-list of revisions), `git-diff-tree` ends up being a veritable fount of
541
-changes. A trivial (but very useful) script called `git-whatchanged` is
542
-included with git which does exactly this, and shows a log of recent
543
-activities.
544
-
545
-To see the whole history of our pitiful little git-tutorial project, you
546
-can do
547
-
548
-----------------
549
-$ git log
550
-----------------
551
-
552
-which shows just the log messages, or if we want to see the log together
553
-with the associated patches use the more complex (and much more
554
-powerful)
555
-
556
-----------------
557
-$ git-whatchanged -p --root
558
-----------------
559
-
560
-and you will see exactly what has changed in the repository over its
561
-short history.
562
-
563
-[NOTE]
564
-The `\--root` flag is a flag to `git-diff-tree` to tell it to
565
-show the initial aka 'root' commit too. Normally you'd probably not
566
-want to see the initial import diff, but since the tutorial project
567
-was started from scratch and is so small, we use it to make the result
568
-a bit more interesting.
569
-
570
-With that, you should now be having some inkling of what git does, and
571
-can explore on your own.
572
-
573
-[NOTE]
574
-Most likely, you are not directly using the core
575
-git Plumbing commands, but using Porcelain like Cogito on top
576
-of it. Cogito works a bit differently and you usually do not
577
-have to run `git-update-index` yourself for changed files (you
578
-do tell underlying git about additions and removals via
579
-`cg-add` and `cg-rm` commands). Just before you make a commit
580
-with `cg-commit`, Cogito figures out which files you modified,
581
-and runs `git-update-index` on them for you.
582
-
583
-
584
-Tagging a version
585
------------------
182
+Using git for collaboration
183
+---------------------------
184
587
-In git, there are two kinds of tags, a "light" one, and an "annotated tag".
185
+Suppose that Alice has started a new project with a git repository in
186
+/home/alice/project, and that Bob, who has a home directory on the
187
+same machine, wants to contribute.
188
589
-A "light" tag is technically nothing more than a branch, except we put
590
-it in the `.git/refs/tags/` subdirectory instead of calling it a `head`.
591
-So the simplest form of tag involves nothing more than
189
+Bob begins with:
190
191
------------------------------------------------
594
-$ git tag my-first-tag
192
+$ git clone /home/alice/project myrepo
193
------------------------------------------------
194
597
-which just writes the current `HEAD` into the `.git/refs/tags/my-first-tag`
598
-file, after which point you can then use this symbolic name for that
599
-particular state. You can, for example, do
600
-
601
-----------------
602
-$ git diff my-first-tag
603
-----------------
604
-
605
-to diff your current state against that tag (which at this point will
606
-obviously be an empty diff, but if you continue to develop and commit
607
-stuff, you can use your tag as an "anchor-point" to see what has changed
608
-since you tagged it.
609
-
610
-An "annotated tag" is actually a real git object, and contains not only a
611
-pointer to the state you want to tag, but also a small tag name and
612
-message, along with optionally a PGP signature that says that yes,
613
-you really did
614
-that tag. You create these annotated tags with either the `-a` or
615
-`-s` flag to `git tag`:
616
-
617
-----------------
618
-$ git tag -s <tagname>
619
-----------------
620
-
621
-which will sign the current `HEAD` (but you can also give it another
622
-argument that specifies the thing to tag, ie you could have tagged the
623
-current `mybranch` point by using `git tag <tagname> mybranch`).
624
-
625
-You normally only do signed tags for major releases or things
626
-like that, while the light-weight tags are useful for any marking you
627
-want to do -- any time you decide that you want to remember a certain
628
-point, just create a private tag for it, and you have a nice symbolic
629
-name for the state at that point.
630
-
631
-
632
-Copying repositories
633
---------------------
634
-
635
-git repositories are normally totally self-sufficient and relocatable
636
-Unlike CVS, for example, there is no separate notion of
637
-"repository" and "working tree". A git repository normally *is* the
638
-working tree, with the local git information hidden in the `.git`
639
-subdirectory. There is nothing else. What you see is what you got.
640
-
641
-[NOTE]
642
-You can tell git to split the git internal information from
643
-the directory that it tracks, but we'll ignore that for now: it's not
644
-how normal projects work, and it's really only meant for special uses.
645
-So the mental model of "the git information is always tied directly to
646
-the working tree that it describes" may not be technically 100%
647
-accurate, but it's a good model for all normal use.
648
-
649
-This has two implications:
650
-
651
- - if you grow bored with the tutorial repository you created (or you've
652
- made a mistake and want to start all over), you can just do simple
653
-+
654
-----------------
655
-$ rm -rf git-tutorial
656
-----------------
657
-+
658
-and it will be gone. There's no external repository, and there's no
659
-history outside the project you created.
660
-
661
- - if you want to move or duplicate a git repository, you can do so. There
662
- is `git clone` command, but if all you want to do is just to
663
- create a copy of your repository (with all the full history that
664
- went along with it), you can do so with a regular
665
- `cp -a git-tutorial new-git-tutorial`.
666
-+
667
-Note that when you've moved or copied a git repository, your git index
668
-file (which caches various information, notably some of the "stat"
669
-information for the files involved) will likely need to be refreshed.
670
-So after you do a `cp -a` to create a new copy, you'll want to do
671
-+
672
-----------------
673
-$ git-update-index --refresh
674
-----------------
675
-+
676
-in the new repository to make sure that the index file is up-to-date.
677
-
678
-Note that the second point is true even across machines. You can
679
-duplicate a remote git repository with *any* regular copy mechanism, be it
680
-`scp`, `rsync` or `wget`.
681
-
682
-When copying a remote repository, you'll want to at a minimum update the
683
-index cache when you do this, and especially with other peoples'
684
-repositories you often want to make sure that the index cache is in some
685
-known state (you don't know *what* they've done and not yet checked in),
686
-so usually you'll precede the `git-update-index` with a
687
-
688
-----------------
689
-$ git-read-tree --reset HEAD
690
-$ git-update-index --refresh
691
-----------------
692
-
693
-which will force a total index re-build from the tree pointed to by `HEAD`.
694
-It resets the index contents to `HEAD`, and then the `git-update-index`
695
-makes sure to match up all index entries with the checked-out files.
696
-If the original repository had uncommitted changes in its
697
-working tree, `git-update-index --refresh` notices them and
698
-tells you they need to be updated.
699
-
700
-The above can also be written as simply
701
-
702
-----------------
703
-$ git reset
704
-----------------
705
-
706
-and in fact a lot of the common git command combinations can be scripted
707
-with the `git xyz` interfaces. You can learn things by just looking
708
-at what the various git scripts do. For example, `git reset` is the
709
-above two lines implemented in `git-reset`, but some things like
710
-`git status` and `git commit` are slightly more complex scripts around
711
-the basic git commands.
712
-
713
-Many (most?) public remote repositories will not contain any of
714
-the checked out files or even an index file, and will *only* contain the
715
-actual core git files. Such a repository usually doesn't even have the
716
-`.git` subdirectory, but has all the git files directly in the
717
-repository.
718
-
719
-To create your own local live copy of such a "raw" git repository, you'd
720
-first create your own subdirectory for the project, and then copy the
721
-raw repository contents into the `.git` directory. For example, to
722
-create your own copy of the git repository, you'd do the following
723
-
724
-----------------
725
-$ mkdir my-git
726
-$ cd my-git
727
-$ rsync -rL rsync://rsync.kernel.org/pub/scm/git/git.git/ .git
728
-----------------
729
-
730
-followed by
731
-
732
-----------------
733
-$ git-read-tree HEAD
734
-----------------
735
-
736
-to populate the index. However, now you have populated the index, and
737
-you have all the git internal files, but you will notice that you don't
738
-actually have any of the working tree files to work on. To get
739
-those, you'd check them out with
740
-
741
-----------------
742
-$ git-checkout-index -u -a
743
-----------------
744
-
745
-where the `-u` flag means that you want the checkout to keep the index
746
-up-to-date (so that you don't have to refresh it afterward), and the
747
-`-a` flag means "check out all files" (if you have a stale copy or an
748
-older version of a checked out tree you may also need to add the `-f`
749
-flag first, to tell git-checkout-index to *force* overwriting of any old
750
-files).
751
-
752
-Again, this can all be simplified with
753
-
754
-----------------
755
-$ git clone rsync://rsync.kernel.org/pub/scm/git/git.git/ my-git
756
-$ cd my-git
757
-$ git checkout
758
-----------------
759
-
760
-which will end up doing all of the above for you.
761
-
762
-You have now successfully copied somebody else's (mine) remote
763
-repository, and checked it out.
764
-
765
-
766
-Creating a new branch
767
----------------------
768
-
769
-Branches in git are really nothing more than pointers into the git
770
-object database from within the `.git/refs/` subdirectory, and as we
771
-already discussed, the `HEAD` branch is nothing but a symlink to one of
772
-these object pointers.
773
-
774
-You can at any time create a new branch by just picking an arbitrary
775
-point in the project history, and just writing the SHA1 name of that
776
-object into a file under `.git/refs/heads/`. You can use any filename you
777
-want (and indeed, subdirectories), but the convention is that the
778
-"normal" branch is called `master`. That's just a convention, though,
779
-and nothing enforces it.
780
-
781
-To show that as an example, let's go back to the git-tutorial repository we
782
-used earlier, and create a branch in it. You do that by simply just
783
-saying that you want to check out a new branch:
784
-
785
-------------
786
-$ git checkout -b mybranch
787
-------------
788
-
789
-will create a new branch based at the current `HEAD` position, and switch
790
-to it.
791
-
792
-[NOTE]
793
-================================================
794
-If you make the decision to start your new branch at some
795
-other point in the history than the current `HEAD`, you can do so by
796
-just telling `git checkout` what the base of the checkout would be.
797
-In other words, if you have an earlier tag or branch, you'd just do
798
-
799
-------------
800
-$ git checkout -b mybranch earlier-commit
801
-------------
802
-
803
-and it would create the new branch `mybranch` at the earlier commit,
804
-and check out the state at that time.
805
-================================================
806
-
807
-You can always just jump back to your original `master` branch by doing
808
-
809
-------------
810
-$ git checkout master
811
-------------
195
+This creates a new directory "myrepo" containing a clone of Alice's
196
+repository. The clone is on an equal footing with the original
197
+project, posessing its own copy of the original project's history.
198
+
199
+Bob then makes some changes and commits them:
200
813
-(or any other branch-name, for that matter) and if you forget which
814
-branch you happen to be on, a simple
201
+------------------------------------------------
202
+(edit files)
203
+$ git commit -a
204
+(repeat as necessary)
205
+------------------------------------------------
206
816
-------------
817
-$ ls -l .git/HEAD
818
-------------
207
+When he's ready, he tells Alice to pull changes from the repository
208
+at /home/bob/myrepo. She does this with:
209
820
-will tell you where it's pointing (Note that on platforms with bad or no
821
-symlink support, you have to execute
210
+------------------------------------------------
211
+$ cd /home/alice/project
212
+$ git pull /home/bob/myrepo
213
+------------------------------------------------
214
823
-------------
824
-$ cat .git/HEAD
825
-------------
215
+This actually pulls changes from the branch in Bob's repository named
216
+"master". Alice could request a different branch by adding the name
217
+of the branch to the end of the git pull command line.
218
827
-instead). To get the list of branches you have, you can say
219
+This merges Bob's changes into her repository; "git whatchanged" will
220
+now show the new commits. If Alice has made her own changes in the
221
+meantime, then Bob's changes will be merged in, and she will need to
222
+manually fix any conflicts.
223
829
-------------
830
-$ git branch
831
-------------
224
+A more cautious Alice might wish to examine Bob's changes before
225
+pulling them. She can do this by creating a temporary branch just
226
+for the purpose of studying Bob's changes:
227
833
-which is nothing more than a simple script around `ls .git/refs/heads`.
834
-There will be asterisk in front of the branch you are currently on.
228
+-------------------------------------
229
+$ git fetch /home/bob/myrepo master:bob-incoming
230
+-------------------------------------
231
836
-Sometimes you may wish to create a new branch _without_ actually
837
-checking it out and switching to it. If so, just use the command
232
+which fetches the changes from Bob's master branch into a new branch
233
+named bob-incoming. (Unlike git pull, git fetch just fetches a copy
234
+of Bob's line of development without doing any merging). Then
235
839
-------------
840
-$ git branch <branchname> [startingpoint]
841
-------------
236
+-------------------------------------
237
+$ git whatchanged -p master..bob-incoming
238
+-------------------------------------
239
843
-which will simply _create_ the branch, but will not do anything further.
844
-You can then later -- once you decide that you want to actually develop
845
-on that branch -- switch to that branch with a regular `git checkout`
846
-with the branchname as the argument.
240
+shows a list of all the changes that Bob made since he branched from
241
+Alice's master branch.
242
243
+After examing those changes, and possibly fixing things, Alice can
244
+pull the changes into her master branch:
245
849
-Merging two branches
850
---------------------
246
+-------------------------------------
247
+$ git checkout master
248
+$ git pull . bob-incoming
249
+-------------------------------------
250
852
-One of the ideas of having a branch is that you do some (possibly
853
-experimental) work in it, and eventually merge it back to the main
854
-branch. So assuming you created the above `mybranch` that started out
855
-being the same as the original `master` branch, let's make sure we're in
856
-that branch, and do some work there.
251
+The last command is a pull from the "bob-incoming" branch in Alice's
252
+own repository.
253
858
-------------------------------------------------
859
-$ git checkout mybranch
860
-$ echo "Work, work, work" >>hello
861
-$ git commit -m 'Some work.' hello
862
-------------------------------------------------
254
+Later, Bob can update his repo with Alice's latest changes using
255
864
-Here, we just added another line to `hello`, and we used a shorthand for
865
-doing both `git-update-index hello` and `git commit` by just giving the
866
-filename directly to `git commit`. The `-m` flag is to give the
867
-commit log message from the command line.
256
+-------------------------------------
257
+$ git pull
258
+-------------------------------------
259
869
-Now, to make it a bit more interesting, let's assume that somebody else
870
-does some work in the original branch, and simulate that by going back
871
-to the master branch, and editing the same file differently there:
260
+Note that he doesn't need to give the path to Alice's repository;
261
+when Bob cloned Alice's repository, git stored the location of her
262
+repository in the file .git/remotes/origin, and that location is used
263
+as the default for pulls.
264
873
-------------
874
-$ git checkout master
875
-------------
876
-
877
-Here, take a moment to look at the contents of `hello`, and notice how they
878
-don't contain the work we just did in `mybranch` -- because that work
879
-hasn't happened in the `master` branch at all. Then do
880
-
881
-------------
882
-$ echo "Play, play, play" >>hello
883
-$ echo "Lots of fun" >>example
884
-$ git commit -m 'Some fun.' hello example
885
-------------
886
-
887
-since the master branch is obviously in a much better mood.
888
-
889
-Now, you've got two branches, and you decide that you want to merge the
890
-work done. Before we do that, let's introduce a cool graphical tool that
891
-helps you view what's going on:
892
-
893
-----------------
894
-$ gitk --all
895
-----------------
896
-
897
-will show you graphically both of your branches (that's what the `\--all`
898
-means: normally it will just show you your current `HEAD`) and their
899
-histories. You can also see exactly how they came to be from a common
900
-source.
901
-
902
-Anyway, let's exit `gitk` (`^Q` or the File menu), and decide that we want
903
-to merge the work we did on the `mybranch` branch into the `master`
904
-branch (which is currently our `HEAD` too). To do that, there's a nice
905
-script called `git merge`, which wants to know which branches you want
906
-to resolve and what the merge is all about:
907
-
908
-------------
909
-$ git merge "Merge work in mybranch" HEAD mybranch
910
-------------
911
-
912
-where the first argument is going to be used as the commit message if
913
-the merge can be resolved automatically.
914
-
915
-Now, in this case we've intentionally created a situation where the
916
-merge will need to be fixed up by hand, though, so git will do as much
917
-of it as it can automatically (which in this case is just merge the `example`
918
-file, which had no differences in the `mybranch` branch), and say:
919
-
920
-----------------
921
- Trying really trivial in-index merge...
922
- fatal: Merge requires file-level merging
923
- Nope.
924
- ...
925
- Auto-merging hello
926
- CONFLICT (content): Merge conflict in hello
927
- Automatic merge failed/prevented; fix up by hand
928
-----------------
929
-
930
-which is way too verbose, but it basically tells you that it failed the
931
-really trivial merge ("Simple merge") and did an "Automatic merge"
932
-instead, but that too failed due to conflicts in `hello`.
933
-
934
-Not to worry. It left the (trivial) conflict in `hello` in the same form you
935
-should already be well used to if you've ever used CVS, so let's just
936
-open `hello` in our editor (whatever that may be), and fix it up somehow.
937
-I'd suggest just making it so that `hello` contains all four lines:
938
-
939
-------------
940
-Hello World
941
-It's a new day for git
942
-Play, play, play
943
-Work, work, work
944
-------------
945
-
946
-and once you're happy with your manual merge, just do a
947
-
948
-------------
949
-$ git commit hello
950
-------------
951
-
952
-which will very loudly warn you that you're now committing a merge
953
-(which is correct, so never mind), and you can write a small merge
954
-message about your adventures in git-merge-land.
955
-
956
-After you're done, start up `gitk \--all` to see graphically what the
957
-history looks like. Notice that `mybranch` still exists, and you can
958
-switch to it, and continue to work with it if you want to. The
959
-`mybranch` branch will not contain the merge, but next time you merge it
960
-from the `master` branch, git will know how you merged it, so you'll not
961
-have to do _that_ merge again.
962
-
963
-Another useful tool, especially if you do not always work in X-Window
964
-environment, is `git show-branch`.
265
+Bob may also notice a branch in his repository that he didn't create:
266
966
-------------------------------------------------
967
-$ git show-branch master mybranch
968
-* [master] Merge work in mybranch
969
- ! [mybranch] Some work.
970
---
971
-- [master] Merge work in mybranch
972
-*+ [mybranch] Some work.
973
-------------------------------------------------
267
+-------------------------------------
268
+$ git branch
269
+* master
270
+ origin
271
+-------------------------------------
272
975
-The first two lines indicate that it is showing the two branches
976
-and the first line of the commit log message from their
977
-top-of-the-tree commits, you are currently on `master` branch
978
-(notice the asterisk `*` character), and the first column for
979
-the later output lines is used to show commits contained in the
980
-`master` branch, and the second column for the `mybranch`
981
-branch. Three commits are shown along with their log messages.
982
-All of them have non blank characters in the first column (`*`
983
-shows an ordinary commit on the current branch, `.` is a merge commit), which
984
-means they are now part of the `master` branch. Only the "Some
985
-work" commit has the plus `+` character in the second column,
986
-because `mybranch` has not been merged to incorporate these
987
-commits from the master branch. The string inside brackets
988
-before the commit log message is a short name you can use to
989
-name the commit. In the above example, 'master' and 'mybranch'
990
-are branch heads. 'master~1' is the first parent of 'master'
991
-branch head. Please see 'git-rev-parse' documentation if you
992
-see more complex cases.
993
-
994
-Now, let's pretend you are the one who did all the work in
995
-`mybranch`, and the fruit of your hard work has finally been merged
996
-to the `master` branch. Let's go back to `mybranch`, and run
997
-resolve to get the "upstream changes" back to your branch.
998
-
999
-------------
1000
-$ git checkout mybranch
1001
-$ git merge "Merge upstream changes." HEAD master
1002
-------------
1003
-
1004
-This outputs something like this (the actual commit object names
1005
-would be different)
1006
-
1007
-----------------
1008
-Updating from ae3a2da... to a80b4aa....
1009
- example | 1 +
1010
- hello | 1 +
1011
- 2 files changed, 2 insertions(+), 0 deletions(-)
1012
-----------------
1013
-
1014
-Because your branch did not contain anything more than what are
1015
-already merged into the `master` branch, the resolve operation did
1016
-not actually do a merge. Instead, it just updated the top of
1017
-the tree of your branch to that of the `master` branch. This is
1018
-often called 'fast forward' merge.
1019
-
1020
-You can run `gitk \--all` again to see how the commit ancestry
1021
-looks like, or run `show-branch`, which tells you this.
273
+The "origin" branch, which was created automatically by "git clone",
274
+is a pristine copy of Alice's master branch; Bob should never commit
275
+to it.
276
1023
-------------------------------------------------
1024
-$ git show-branch master mybranch
1025
-! [master] Merge work in mybranch
1026
- * [mybranch] Merge work in mybranch
1027
---
1028
-------------------------------------------------
277
+If Bob later decides to work from a different host, he can still
278
+perform clones and pulls using the ssh protocol:
279
280
+-------------------------------------
281
+$ git clone alice.org:/home/alice/project myrepo
282
+-------------------------------------
283
1031
-Merging external work
1032
----------------------
1033
-
1034
-It's usually much more common that you merge with somebody else than
1035
-merging with your own branches, so it's worth pointing out that git
1036
-makes that very easy too, and in fact, it's not that different from
1037
-doing a `git merge`. In fact, a remote merge ends up being nothing
1038
-more than "fetch the work from a remote repository into a temporary tag"
1039
-followed by a `git merge`.
1040
-
1041
-Fetching from a remote repository is done by, unsurprisingly,
1042
-`git fetch`:
1043
-
1044
-----------------
1045
-$ git fetch <remote-repository>
1046
-----------------
1047
-
1048
-One of the following transports can be used to name the
1049
-repository to download from:
1050
-
1051
-Rsync::
1052
- `rsync://remote.machine/path/to/repo.git/`
1053
-+
1054
-Rsync transport is usable for both uploading and downloading,
1055
-but is completely unaware of what git does, and can produce
1056
-unexpected results when you download from the public repository
1057
-while the repository owner is uploading into it via `rsync`
1058
-transport. Most notably, it could update the files under
1059
-`refs/` which holds the object name of the topmost commits
1060
-before uploading the files in `objects/` -- the downloader would
1061
-obtain head commit object name while that object itself is still
1062
-not available in the repository. For this reason, it is
1063
-considered deprecated.
1064
-
1065
-SSH::
1066
- `remote.machine:/path/to/repo.git/` or
1067
-+
1068
-`ssh://remote.machine/path/to/repo.git/`
1069
-+
1070
-This transport can be used for both uploading and downloading,
1071
-and requires you to have a log-in privilege over `ssh` to the
1072
-remote machine. It finds out the set of objects the other side
1073
-lacks by exchanging the head commits both ends have and
1074
-transfers (close to) minimum set of objects. It is by far the
1075
-most efficient way to exchange git objects between repositories.
1076
-
1077
-Local directory::
1078
- `/path/to/repo.git/`
1079
-+
1080
-This transport is the same as SSH transport but uses `sh` to run
1081
-both ends on the local machine instead of running other end on
1082
-the remote machine via `ssh`.
1083
-
1084
-git Native::
1085
- `git://remote.machine/path/to/repo.git/`
1086
-+
1087
-This transport was designed for anonymous downloading. Like SSH
1088
-transport, it finds out the set of objects the downstream side
1089
-lacks and transfers (close to) minimum set of objects.
1090
-
1091
-HTTP(S)::
1092
- `http://remote.machine/path/to/repo.git/`
1093
-+
1094
-Downloader from http and https URL
1095
-first obtains the topmost commit object name from the remote site
1096
-by looking at the specified refname under `repo.git/refs/` directory,
1097
-and then tries to obtain the
1098
-commit object by downloading from `repo.git/objects/xx/xxx\...`
1099
-using the object name of that commit object. Then it reads the
1100
-commit object to find out its parent commits and the associate
1101
-tree object; it repeats this process until it gets all the
1102
-necessary objects. Because of this behaviour, they are
1103
-sometimes also called 'commit walkers'.
1104
-+
1105
-The 'commit walkers' are sometimes also called 'dumb
1106
-transports', because they do not require any git aware smart
1107
-server like git Native transport does. Any stock HTTP server
1108
-that does not even support directory index would suffice. But
1109
-you must prepare your repository with `git-update-server-info`
1110
-to help dumb transport downloaders.
1111
-+
1112
-There are (confusingly enough) `git-ssh-fetch` and `git-ssh-upload`
1113
-programs, which are 'commit walkers'; they outlived their
1114
-usefulness when git Native and SSH transports were introduced,
1115
-and not used by `git pull` or `git push` scripts.
1116
-
1117
-Once you fetch from the remote repository, you `resolve` that
1118
-with your current branch.
1119
-
1120
-However -- it's such a common thing to `fetch` and then
1121
-immediately `resolve`, that it's called `git pull`, and you can
1122
-simply do
1123
-
1124
-----------------
1125
-$ git pull <remote-repository>
1126
-----------------
1127
-
1128
-and optionally give a branch-name for the remote end as a second
1129
-argument.
1130
-
1131
-[NOTE]
1132
-You could do without using any branches at all, by
1133
-keeping as many local repositories as you would like to have
1134
-branches, and merging between them with `git pull`, just like
1135
-you merge between branches. The advantage of this approach is
1136
-that it lets you keep set of files for each `branch` checked
1137
-out and you may find it easier to switch back and forth if you
1138
-juggle multiple lines of development simultaneously. Of
1139
-course, you will pay the price of more disk usage to hold
1140
-multiple working trees, but disk space is cheap these days.
1141
-
1142
-[NOTE]
1143
-You could even pull from your own repository by
1144
-giving '.' as <remote-repository> parameter to `git pull`. This
1145
-is useful when you want to merge a local branch (or more, if you
1146
-are making an Octopus) into the current branch.
1147
-
1148
-It is likely that you will be pulling from the same remote
1149
-repository from time to time. As a short hand, you can store
1150
-the remote repository URL in a file under .git/remotes/
1151
-directory, like this:
284
+Alternatively, git has a native protocol, or can use rsync or http;
285
+see gitlink:git-pull[1] for details.
286
1153
-------------------------------------------------
1154
-$ mkdir -p .git/remotes/
1155
-$ cat >.git/remotes/linus <<\EOF
1156
-URL: http://www.kernel.org/pub/scm/git/git.git/
1157
-EOF
1158
-------------------------------------------------
287
+Git can also be used in a CVS-like mode, with a central repository
288
+that various users push changes to; see gitlink:git-push[1] and
289
+link:cvs-migration.html[git for CVS users].
290
1160
-and use the filename to `git pull` instead of the full URL.
1161
-The URL specified in such file can even be a prefix
1162
-of a full URL, like this:
291
+Keeping track of history
292
+------------------------
293
1164
-------------------------------------------------
1165
-$ cat >.git/remotes/jgarzik <<\EOF
1166
-URL: http://www.kernel.org/pub/scm/linux/git/jgarzik/
1167
-EOF
1168
-------------------------------------------------
294
+Git history is represented as a series of interrelated commits. The
295
+most recent commit in the currently checked-out branch can always be
296
+referred to as HEAD, and the "parent" of any commit can always be
297
+referred to by appending a caret, "^", to the end of the name of the
298
+commit. So, for example,
299
300
+-------------------------------------
301
+git diff HEAD^ HEAD
302
+-------------------------------------
303
1171
-Examples.
304
+shows the difference between the most-recently checked-in state of
305
+the tree and the previous state, and
306
1173
-. `git pull linus`
1174
-. `git pull linus tag v0.99.1`
1175
-. `git pull jgarzik/netdev-2.6.git/ e100`
307
+-------------------------------------
308
+git diff HEAD^^ HEAD^
309
+-------------------------------------
310
1177
-the above are equivalent to:
311
+shows the difference between that previous state and the state two
312
+commits ago. Also, HEAD~5 can be used as a shorthand for HEAD^^^^^,
313
+and more generally HEAD~n can refer to the nth previous commit.
314
+Commits representing merges have more than one parent, and you can
315
+specify which parent to follow in that case; see
316
+gitlink:git-rev-parse[1].
317
1179
-. `git pull http://www.kernel.org/pub/scm/git/git.git/ HEAD`
1180
-. `git pull http://www.kernel.org/pub/scm/git/git.git/ tag v0.99.1`
1181
-. `git pull http://www.kernel.org/pub/.../jgarzik/netdev-2.6.git e100`
318
+The name of a branch can also be used to refer to the most recent
319
+commit on that branch; so you can also say things like
320
321
+-------------------------------------
322
+git diff HEAD experimental
323
+-------------------------------------
324
1184
-How does the merge work?
1185
-------------------------
325
+to see the difference between the most-recently committed tree in
326
+the current branch and the most-recently committed tree in the
327
+experimental branch.
328
1187
-We said this tutorial shows what plumbing does to help you cope
1188
-with the porcelain that isn't flushing, but we so far did not
1189
-talk about how the merge really works. If you are following
1190
-this tutorial the first time, I'd suggest to skip to "Publishing
1191
-your work" section and come back here later.
1192
-
1193
-OK, still with me? To give us an example to look at, let's go
1194
-back to the earlier repository with "hello" and "example" file,
1195
-and bring ourselves back to the pre-merge state:
1196
-
1197
-------------
1198
-$ git show-branch --more=3 master mybranch
1199
-! [master] Merge work in mybranch
1200
- * [mybranch] Merge work in mybranch
1201
---
1202
-+* [master^2] Some work.
1203
-+* [master^] Some fun.
1204
-------------
1205
-
1206
-Remember, before running `git merge`, our `master` head was at
1207
-"Some fun." commit, while our `mybranch` head was at "Some
1208
-work." commit.
1209
-
1210
-------------
1211
-$ git checkout mybranch
1212
-$ git reset --hard master^2
1213
-$ git checkout master
1214
-$ git reset --hard master^
1215
-------------
1216
-
1217
-After rewinding, the commit structure should look like this:
1218
-
1219
-------------
1220
-$ git show-branch
1221
-* [master] Some fun.
1222
- ! [mybranch] Some work.
1223
---
1224
- + [mybranch] Some work.
1225
-* [master] Some fun.
1226
-*+ [mybranch^] New day.
1227
-------------
1228
-
1229
-Now we are ready to experiment with the merge by hand.
1230
-
1231
-`git merge` command, when merging two branches, uses 3-way merge
1232
-algorithm. First, it finds the common ancestor between them.
1233
-The command it uses is `git-merge-base`:
1234
-
1235
-------------
1236
-$ mb=$(git-merge-base HEAD mybranch)
1237
-------------
1238
-
1239
-The command writes the commit object name of the common ancestor
1240
-to the standard output, so we captured its output to a variable,
1241
-because we will be using it in the next step. BTW, the common
1242
-ancestor commit is the "New day." commit in this case. You can
1243
-tell it by:
1244
-
1245
-------------
1246
-$ git-name-rev $mb
1247
-my-first-tag
1248
-------------
1249
-
1250
-After finding out a common ancestor commit, the second step is
1251
-this:
1252
-
1253
-------------
1254
-$ git-read-tree -m -u $mb HEAD mybranch
1255
-------------
1256
-
1257
-This is the same `git-read-tree` command we have already seen,
1258
-but it takes three trees, unlike previous examples. This reads
1259
-the contents of each tree into different 'stage' in the index
1260
-file (the first tree goes to stage 1, the second stage 2,
1261
-etc.). After reading three trees into three stages, the paths
1262
-that are the same in all three stages are 'collapsed' into stage
1263
-0. Also paths that are the same in two of three stages are
1264
-collapsed into stage 0, taking the SHA1 from either stage 2 or
1265
-stage 3, whichever is different from stage 1 (i.e. only one side
1266
-changed from the common ancestor).
1267
-
1268
-After 'collapsing' operation, paths that are different in three
1269
-trees are left in non-zero stages. At this point, you can
1270
-inspect the index file with this command:
1271
-
1272
-------------
1273
-$ git-ls-files --stage
1274
-100644 7f8b141b65fdcee47321e399a2598a235a032422 0 example
1275
-100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello
1276
-100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello
1277
-100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello
1278
-------------
1279
-
1280
-In our example of only two files, we did not have unchanged
1281
-files so only 'example' resulted in collapsing, but in real-life
1282
-large projects, only small number of files change in one commit,
1283
-and this 'collapsing' tends to trivially merge most of the paths
1284
-fairly quickly, leaving only a handful the real changes in non-zero
1285
-stages.
1286
-
1287
-To look at only non-zero stages, use `\--unmerged` flag:
1288
-
1289
-------------
1290
-$ git-ls-files --unmerged
1291
-100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello
1292
-100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello
1293
-100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello
1294
-------------
1295
-
1296
-The next step of merging is to merge these three versions of the
1297
-file, using 3-way merge. This is done by giving
1298
-`git-merge-one-file` command as one of the arguments to
1299
-`git-merge-index` command:
1300
-
1301
-------------
1302
-$ git-merge-index git-merge-one-file hello
1303
-Auto-merging hello.
1304
-merge: warning: conflicts during merge
1305
-ERROR: Merge conflict in hello.
1306
-fatal: merge program failed
1307
-------------
1308
-
1309
-`git-merge-one-file` script is called with parameters to
1310
-describe those three versions, and is responsible to leave the
1311
-merge results in the working tree.
1312
-It is a fairly straightforward shell script, and
1313
-eventually calls `merge` program from RCS suite to perform a
1314
-file-level 3-way merge. In this case, `merge` detects
1315
-conflicts, and the merge result with conflict marks is left in
1316
-the working tree.. This can be seen if you run `ls-files
1317
---stage` again at this point:
1318
-
1319
-------------
1320
-$ git-ls-files --stage
1321
-100644 7f8b141b65fdcee47321e399a2598a235a032422 0 example
1322
-100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello
1323
-100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello
1324
-100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello
1325
-------------
1326
-
1327
-This is the state of the index file and the working file after
1328
-`git merge` returns control back to you, leaving the conflicting
1329
-merge for you to resolve. Notice that the path `hello` is still
1330
-unmerged, and what you see with `git diff` at this point is
1331
-differences since stage 2 (i.e. your version).
1332
-
1333
-
1334
-Publishing your work
1335
---------------------
1336
-
1337
-So we can use somebody else's work from a remote repository; but
1338
-how can *you* prepare a repository to let other people pull from
1339
-it?
1340
-
1341
-Your do your real work in your working tree that has your
1342
-primary repository hanging under it as its `.git` subdirectory.
1343
-You *could* make that repository accessible remotely and ask
1344
-people to pull from it, but in practice that is not the way
1345
-things are usually done. A recommended way is to have a public
1346
-repository, make it reachable by other people, and when the
1347
-changes you made in your primary working tree are in good shape,
1348
-update the public repository from it. This is often called
1349
-'pushing'.
1350
-
1351
-[NOTE]
1352
-This public repository could further be mirrored, and that is
1353
-how git repositories at `kernel.org` are managed.
1354
-
1355
-Publishing the changes from your local (private) repository to
1356
-your remote (public) repository requires a write privilege on
1357
-the remote machine. You need to have an SSH account there to
1358
-run a single command, `git-receive-pack`.
1359
-
1360
-First, you need to create an empty repository on the remote
1361
-machine that will house your public repository. This empty
1362
-repository will be populated and be kept up-to-date by pushing
1363
-into it later. Obviously, this repository creation needs to be
1364
-done only once.
1365
-
1366
-[NOTE]
1367
-`git push` uses a pair of programs,
1368
-`git-send-pack` on your local machine, and `git-receive-pack`
1369
-on the remote machine. The communication between the two over
1370
-the network internally uses an SSH connection.
1371
-
1372
-Your private repository's git directory is usually `.git`, but
1373
-your public repository is often named after the project name,
1374
-i.e. `<project>.git`. Let's create such a public repository for
1375
-project `my-git`. After logging into the remote machine, create
1376
-an empty directory:
1377
-
1378
-------------
1379
-$ mkdir my-git.git
1380
-------------
1381
-
1382
-Then, make that directory into a git repository by running
1383
-`git init-db`, but this time, since its name is not the usual
1384
-`.git`, we do things slightly differently:
1385
-
1386
-------------
1387
-$ GIT_DIR=my-git.git git-init-db
1388
-------------
1389
-
1390
-Make sure this directory is available for others you want your
1391
-changes to be pulled by via the transport of your choice. Also
1392
-you need to make sure that you have the `git-receive-pack`
1393
-program on the `$PATH`.
1394
-
1395
-[NOTE]
1396
-Many installations of sshd do not invoke your shell as the login
1397
-shell when you directly run programs; what this means is that if
1398
-your login shell is `bash`, only `.bashrc` is read and not
1399
-`.bash_profile`. As a workaround, make sure `.bashrc` sets up
1400
-`$PATH` so that you can run `git-receive-pack` program.
1401
-
1402
-[NOTE]
1403
-If you plan to publish this repository to be accessed over http,
1404
-you should do `chmod +x my-git.git/hooks/post-update` at this
1405
-point. This makes sure that every time you push into this
1406
-repository, `git-update-server-info` is run.
1407
-
1408
-Your "public repository" is now ready to accept your changes.
1409
-Come back to the machine you have your private repository. From
1410
-there, run this command:
1411
-
1412
-------------
1413
-$ git push <public-host>:/path/to/my-git.git master
1414
-------------
1415
-
1416
-This synchronizes your public repository to match the named
1417
-branch head (i.e. `master` in this case) and objects reachable
1418
-from them in your current repository.
1419
-
1420
-As a real example, this is how I update my public git
1421
-repository. Kernel.org mirror network takes care of the
1422
-propagation to other publicly visible machines:
1423
-
1424
-------------
1425
-$ git push master.kernel.org:/pub/scm/git/git.git/
1426
-------------
1427
-
1428
-
1429
-Packing your repository
1430
------------------------
329
+But you may find it more useful to see the list of commits made in
330
+the experimental branch but not in the current branch, and
331
1432
-Earlier, we saw that one file under `.git/objects/??/` directory
1433
-is stored for each git object you create. This representation
1434
-is efficient to create atomically and safely, but
1435
-not so convenient to transport over the network. Since git objects are
1436
-immutable once they are created, there is a way to optimize the
1437
-storage by "packing them together". The command
1438
-
1439
-------------
1440
-$ git repack
1441
-------------
1442
-
1443
-will do it for you. If you followed the tutorial examples, you
1444
-would have accumulated about 17 objects in `.git/objects/??/`
1445
-directories by now. `git repack` tells you how many objects it
1446
-packed, and stores the packed file in `.git/objects/pack`
1447
-directory.
1448
-
1449
-[NOTE]
1450
-You will see two files, `pack-\*.pack` and `pack-\*.idx`,
1451
-in `.git/objects/pack` directory. They are closely related to
1452
-each other, and if you ever copy them by hand to a different
1453
-repository for whatever reason, you should make sure you copy
1454
-them together. The former holds all the data from the objects
1455
-in the pack, and the latter holds the index for random
1456
-access.
1457
-
1458
-If you are paranoid, running `git-verify-pack` command would
1459
-detect if you have a corrupt pack, but do not worry too much.
1460
-Our programs are always perfect ;-).
1461
-
1462
-Once you have packed objects, you do not need to leave the
1463
-unpacked objects that are contained in the pack file anymore.
1464
-
1465
-------------
1466
-$ git prune-packed
1467
-------------
1468
-
1469
-would remove them for you.
1470
-
1471
-You can try running `find .git/objects -type f` before and after
1472
-you run `git prune-packed` if you are curious. Also `git
1473
-count-objects` would tell you how many unpacked objects are in
1474
-your repository and how much space they are consuming.
1475
-
1476
-[NOTE]
1477
-`git pull` is slightly cumbersome for HTTP transport, as a
1478
-packed repository may contain relatively few objects in a
1479
-relatively large pack. If you expect many HTTP pulls from your
1480
-public repository you might want to repack & prune often, or
1481
-never.
1482
-
1483
-If you run `git repack` again at this point, it will say
1484
-"Nothing to pack". Once you continue your development and
1485
-accumulate the changes, running `git repack` again will create a
1486
-new pack, that contains objects created since you packed your
1487
-repository the last time. We recommend that you pack your project
1488
-soon after the initial import (unless you are starting your
1489
-project from scratch), and then run `git repack` every once in a
1490
-while, depending on how active your project is.
1491
-
1492
-When a repository is synchronized via `git push` and `git pull`
1493
-objects packed in the source repository are usually stored
1494
-unpacked in the destination, unless rsync transport is used.
1495
-While this allows you to use different packing strategies on
1496
-both ends, it also means you may need to repack both
1497
-repositories every once in a while.
1498
-
1499
-
1500
-Working with Others
1501
--------------------
1502
-
1503
-Although git is a truly distributed system, it is often
1504
-convenient to organize your project with an informal hierarchy
1505
-of developers. Linux kernel development is run this way. There
1506
-is a nice illustration (page 17, "Merges to Mainline") in Randy
1507
-Dunlap's presentation (`http://tinyurl.com/a2jdg`).
1508
-
1509
-It should be stressed that this hierarchy is purely *informal*.
1510
-There is nothing fundamental in git that enforces the "chain of
1511
-patch flow" this hierarchy implies. You do not have to pull
1512
-from only one remote repository.
1513
-
1514
-A recommended workflow for a "project lead" goes like this:
1515
-
1516
-1. Prepare your primary repository on your local machine. Your
1517
- work is done there.
1518
-
1519
-2. Prepare a public repository accessible to others.
1520
-+
1521
-If other people are pulling from your repository over dumb
1522
-transport protocols (HTTP), you need to keep this repository
1523
-'dumb transport friendly'. After `git init-db`,
1524
-`$GIT_DIR/hooks/post-update` copied from the standard templates
1525
-would contain a call to `git-update-server-info` but the
1526
-`post-update` hook itself is disabled by default -- enable it
1527
-with `chmod +x post-update`. This makes sure `git-update-server-info`
1528
-keeps the necessary files up-to-date.
1529
-
1530
-3. Push into the public repository from your primary
1531
- repository.
1532
-
1533
-4. `git repack` the public repository. This establishes a big
1534
- pack that contains the initial set of objects as the
1535
- baseline, and possibly `git prune` if the transport
1536
- used for pulling from your repository supports packed
1537
- repositories.
1538
-
1539
-5. Keep working in your primary repository. Your changes
1540
- include modifications of your own, patches you receive via
1541
- e-mails, and merges resulting from pulling the "public"
1542
- repositories of your "subsystem maintainers".
1543
-+
1544
-You can repack this private repository whenever you feel like.
1545
-
1546
-6. Push your changes to the public repository, and announce it
1547
- to the public.
1548
-
1549
-7. Every once in a while, "git repack" the public repository.
1550
- Go back to step 5. and continue working.
1551
-
1552
-
1553
-A recommended work cycle for a "subsystem maintainer" who works
1554
-on that project and has an own "public repository" goes like this:
1555
-
1556
-1. Prepare your work repository, by `git clone` the public
1557
- repository of the "project lead". The URL used for the
1558
- initial cloning is stored in `.git/remotes/origin`.
1559
-
1560
-2. Prepare a public repository accessible to others, just like
1561
- the "project lead" person does.
1562
-
1563
-3. Copy over the packed files from "project lead" public
1564
- repository to your public repository, unless the "project
1565
- lead" repository lives on the same machine as yours. In the
1566
- latter case, you can use `objects/info/alternates` file to
1567
- point at the repository you are borrowing from.
1568
-
1569
-4. Push into the public repository from your primary
1570
- repository. Run `git repack`, and possibly `git prune` if the
1571
- transport used for pulling from your repository supports
1572
- packed repositories.
1573
-
1574
-5. Keep working in your primary repository. Your changes
1575
- include modifications of your own, patches you receive via
1576
- e-mails, and merges resulting from pulling the "public"
1577
- repositories of your "project lead" and possibly your
1578
- "sub-subsystem maintainers".
1579
-+
1580
-You can repack this private repository whenever you feel
1581
-like.
1582
-
1583
-6. Push your changes to your public repository, and ask your
1584
- "project lead" and possibly your "sub-subsystem
1585
- maintainers" to pull from it.
1586
-
1587
-7. Every once in a while, `git repack` the public repository.
1588
- Go back to step 5. and continue working.
1589
-
1590
-
1591
-A recommended work cycle for an "individual developer" who does
1592
-not have a "public" repository is somewhat different. It goes
1593
-like this:
1594
-
1595
-1. Prepare your work repository, by `git clone` the public
1596
- repository of the "project lead" (or a "subsystem
1597
- maintainer", if you work on a subsystem). The URL used for
1598
- the initial cloning is stored in `.git/remotes/origin`.
1599
-
1600
-2. Do your work in your repository on 'master' branch.
1601
-
1602
-3. Run `git fetch origin` from the public repository of your
1603
- upstream every once in a while. This does only the first
1604
- half of `git pull` but does not merge. The head of the
1605
- public repository is stored in `.git/refs/heads/origin`.
1606
-
1607
-4. Use `git cherry origin` to see which ones of your patches
1608
- were accepted, and/or use `git rebase origin` to port your
1609
- unmerged changes forward to the updated upstream.
1610
-
1611
-5. Use `git format-patch origin` to prepare patches for e-mail
1612
- submission to your upstream and send it out. Go back to
1613
- step 2. and continue.
332
+-------------------------------------
333
+git whatchanged HEAD..experimental
334
+-------------------------------------
335
336
+will do that, just as
337
1616
-Working with Others, Shared Repository Style
1617
---------------------------------------------
1618
-
1619
-If you are coming from CVS background, the style of cooperation
1620
-suggested in the previous section may be new to you. You do not
1621
-have to worry. git supports "shared public repository" style of
1622
-cooperation you are probably more familiar with as well.
338
+-------------------------------------
339
+git whatchanged experimental..HEAD
340
+-------------------------------------
341
1624
-For this, set up a public repository on a machine that is
1625
-reachable via SSH by people with "commit privileges". Put the
1626
-committers in the same user group and make the repository
1627
-writable by that group. Make sure their umasks are set up to
1628
-allow group members to write into directories other members
1629
-have created.
342
+will show the list of commits made on the HEAD but not included in
343
+experimental.
344
1631
-You, as an individual committer, then:
345
+You can also give commits convenient names of your own: after running
346
1633
-- First clone the shared repository to a local repository:
1634
-------------------------------------------------
1635
-$ git clone repo.shared.xz:/pub/scm/project.git/ my-project
1636
-$ cd my-project
1637
-$ hack away
1638
-------------------------------------------------
347
+-------------------------------------
348
+$ git-tag v2.5 HEAD^^
349
+-------------------------------------
350
1640
-- Merge the work others might have done while you were hacking
1641
- away:
1642
-------------------------------------------------
1643
-$ git pull origin
1644
-$ test the merge result
1645
-------------------------------------------------
1646
-[NOTE]
1647
-================================
1648
-The first `git clone` would have placed the following in
1649
-`my-project/.git/remotes/origin` file, and that's why this and
1650
-the next step work.
1651
-------------
1652
-URL: repo.shared.xz:/pub/scm/project.git/ my-project
1653
-Pull: master:origin
1654
-------------
1655
-================================
1656
-
1657
-- push your work as the new head of the shared
1658
- repository.
1659
-------------------------------------------------
1660
-$ git push origin master
1661
-------------------------------------------------
1662
-If somebody else pushed into the same shared repository while
1663
-you were working locally, `git push` in the last step would
1664
-complain, telling you that the remote `master` head does not
1665
-fast forward. You need to pull and merge those other changes
1666
-back before you push your work when it happens.
351
+you can refer to HEAD^^ by the name "v2.5". If you intend to share
352
+this name with other people (for example, to identify a release
353
+version), you should create a "tag" object, and perhaps sign it; see
354
+gitlink:git-tag[1] for details.
355
356
+You can revisit the old state of a tree, and make further
357
+modifications if you wish, using git branch: the command
358
1669
-Advanced Shared Repository Management
359
+-------------------------------------
360
+$ git branch stable-release v2.5
361
-------------------------------------
362
1672
-Being able to push into a shared repository means being able to
1673
-write into it. If your developers are coming over the network,
1674
-this means you, as the repository administrator, need to give
1675
-each of them an SSH access to the shared repository machine.
1676
-
1677
-In some cases, though, you may not want to give a normal shell
1678
-account to them, but want to restrict them to be able to only
1679
-do `git push` into the repository and nothing else.
1680
-
1681
-You can achieve this by setting the login shell of your
1682
-developers on the shared repository host to `git-shell` program.
1683
-
1684
-[NOTE]
1685
-Most likely you would also need to list `git-shell` program in
1686
-`/etc/shells` file.
1687
-
1688
-This restricts the set of commands that can be run from incoming
1689
-SSH connection for these users to only `receive-pack` and
1690
-`upload-pack`, so the only thing they can do are `git fetch` and
1691
-`git push`.
1692
-
1693
-You still need to create UNIX user accounts for each developer,
1694
-and put them in the same group. Make sure that the repository
1695
-shared among these developers is writable by that group.
1696
-
1697
-. Initializing the shared repository with `git-init-db --shared`
1698
-helps somewhat.
1699
-
1700
-. Run the following in the shared repository:
1701
-+
1702
-------------
1703
-$ chgrp -R $group repo.git
1704
-$ find repo.git -type d -print | xargs chmod ug+rwx,g+s
1705
-$ GIT_DIR=repo.git git repo-config core.sharedrepository true
1706
-------------
1707
-
1708
-The above measures make sure that directories lazily created in
1709
-`$GIT_DIR` are writable by group members. You, as the
1710
-repository administrator, are still responsible to make sure
1711
-your developers belong to that shared repository group and set
1712
-their umask to a value no stricter than 027 (i.e. at least allow
1713
-reading and searching by group members).
1714
-
1715
-You can implement finer grained branch policies using update
1716
-hooks. There is a document ("control access to branches") in
1717
-Documentation/howto by Carl Baldwin and JC outlining how to (1)
1718
-limit access to branch per user, (2) forbid overwriting existing
1719
-tags.
1720
-
1721
-
1722
-Bundling your work together
1723
----------------------------
363
+will create a new branch named "stable-release" starting from the
364
+commit which you tagged with the name v2.5.
365
+
366
+You can reset the state of any branch to an earlier commit at any
367
+time with
368
+
369
+-------------------------------------
370
+$ git reset --hard v2.5
371
+-------------------------------------
372
1725
-It is likely that you will be working on more than one thing at
1726
-a time. It is easy to manage those more-or-less independent tasks
1727
-using branches with git.
1728
-
1729
-We have already seen how branches work previously,
1730
-with "fun and work" example using two branches. The idea is the
1731
-same if there are more than two branches. Let's say you started
1732
-out from "master" head, and have some new code in the "master"
1733
-branch, and two independent fixes in the "commit-fix" and
1734
-"diff-fix" branches:
1735
-
1736
-------------
1737
-$ git show-branch
1738
-! [commit-fix] Fix commit message normalization.
1739
- ! [diff-fix] Fix rename detection.
1740
- * [master] Release candidate #1
1741
----
1742
- + [diff-fix] Fix rename detection.
1743
- + [diff-fix~1] Better common substring algorithm.
1744
-+ [commit-fix] Fix commit message normalization.
1745
- * [master] Release candidate #1
1746
-++* [diff-fix~2] Pretty-print messages.
1747
-------------
1748
-
1749
-Both fixes are tested well, and at this point, you want to merge
1750
-in both of them. You could merge in 'diff-fix' first and then
1751
-'commit-fix' next, like this:
1752
-
1753
-------------
1754
-$ git merge 'Merge fix in diff-fix' master diff-fix
1755
-$ git merge 'Merge fix in commit-fix' master commit-fix
1756
-------------
1757
-
1758
-Which would result in:
1759
-
1760
-------------
1761
-$ git show-branch
1762
-! [commit-fix] Fix commit message normalization.
1763
- ! [diff-fix] Fix rename detection.
1764
- * [master] Merge fix in commit-fix
1765
----
1766
- - [master] Merge fix in commit-fix
1767
-+ * [commit-fix] Fix commit message normalization.
1768
- - [master~1] Merge fix in diff-fix
1769
- +* [diff-fix] Fix rename detection.
1770
- +* [diff-fix~1] Better common substring algorithm.
1771
- * [master~2] Release candidate #1
1772
-++* [master~3] Pretty-print messages.
1773
-------------
1774
-
1775
-However, there is no particular reason to merge in one branch
1776
-first and the other next, when what you have are a set of truly
1777
-independent changes (if the order mattered, then they are not
1778
-independent by definition). You could instead merge those two
1779
-branches into the current branch at once. First let's undo what
1780
-we just did and start over. We would want to get the master
1781
-branch before these two merges by resetting it to 'master~2':
1782
-
1783
-------------
1784
-$ git reset --hard master~2
1785
-------------
1786
-
1787
-You can make sure 'git show-branch' matches the state before
1788
-those two 'git merge' you just did. Then, instead of running
1789
-two 'git merge' commands in a row, you would pull these two
1790
-branch heads (this is known as 'making an Octopus'):
1791
-
1792
-------------
1793
-$ git pull . commit-fix diff-fix
1794
-$ git show-branch
1795
-! [commit-fix] Fix commit message normalization.
1796
- ! [diff-fix] Fix rename detection.
1797
- * [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
1798
----
1799
- - [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
1800
-+ * [commit-fix] Fix commit message normalization.
1801
- +* [diff-fix] Fix rename detection.
1802
- +* [diff-fix~1] Better common substring algorithm.
1803
- * [master~1] Release candidate #1
1804
-++* [master~2] Pretty-print messages.
1805
-------------
1806
-
1807
-Note that you should not do Octopus because you can. An octopus
1808
-is a valid thing to do and often makes it easier to view the
1809
-commit history if you are pulling more than two independent
1810
-changes at the same time. However, if you have merge conflicts
1811
-with any of the branches you are merging in and need to hand
1812
-resolve, that is an indication that the development happened in
1813
-those branches were not independent after all, and you should
1814
-merge two at a time, documenting how you resolved the conflicts,
1815
-and the reason why you preferred changes made in one side over
1816
-the other. Otherwise it would make the project history harder
1817
-to follow, not easier.
1818
-
1819
-[ to be continued.. cvsimports ]
373
+This will remove all later commits from this branch and reset the
374
+working tree to the state it had when the given commit was made. If
375
+this branch is the only branch containing the later commits, those
376
+later changes will be lost. Don't use "git reset" on a
377
+publicly-visible branch that other developers pull from, as git will
378
+be confused by history that disappears in this way.
379
+
380
+Next Steps
381
+----------
382
+
383
+Some good commands to explore next:
384
+
385
+ * gitlink:git-diff[1]: This flexible command does much more than
386
+ we've seen in the few examples above.
387
+
388
+ * gitlink:git-format-patch[1], gitlink:git-am[1]: These convert
389
+ series of git commits into emailed patches, and vice versa,
390
+ useful for projects such as the linux kernel which rely heavily
391
+ on emailed patches.
392
+
393
+ * gitlink:git-bisect[1]: When there is a regression in your
394
+ project, one way to track down the bug is by searching through
395
+ the history to find the exact commit that's to blame. Git bisect
396
+ can help you perform a binary search for that commit. It is
397
+ smart enough to perform a close-to-optimal search even in the
398
+ case of complex non-linear history with lots of merged branches.
399
+
400
+Other good starting points include link:everyday.html[Everday GIT
401
+with 20 Commands Or So] and link:cvs-migration.html[git for CVS
402
+users]. Also, link:core-tutorial.html[A short git tutorial] gives an
403
+introduction to lower-level git commands for advanced users and
404
+developers.