@matheusbsbs / matheus-bagliano / commits / 927a503cd0
Fork 0

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.