1GITCORE-TUTORIAL(7)               Git Manual               GITCORE-TUTORIAL(7)
2
3
4

NAME

6       gitcore-tutorial - A Git core tutorial for developers
7

SYNOPSIS

9       git *
10

DESCRIPTION

12       This tutorial explains how to use the "core" Git commands to set up and
13       work with a Git repository.
14
15       If you just need to use Git as a revision control system you may prefer
16       to start with "A Tutorial Introduction to Git" (gittutorial(7)) or the
17       Git User Manual[1].
18
19       However, an understanding of these low-level tools can be helpful if
20       you want to understand Git’s internals.
21
22       The core Git is often called "plumbing", with the prettier user
23       interfaces on top of it called "porcelain". You may not want to use the
24       plumbing directly very often, but it can be good to know what the
25       plumbing does when the porcelain isn’t flushing.
26
27       Back when this document was originally written, many porcelain commands
28       were shell scripts. For simplicity, it still uses them as examples to
29       illustrate how plumbing is fit together to form the porcelain commands.
30       The source tree includes some of these scripts in contrib/examples/ for
31       reference. Although these are not implemented as shell scripts anymore,
32       the description of what the plumbing layer commands do is still valid.
33
34           Note
35           Deeper technical details are often marked as Notes, which you can
36           skip on your first reading.
37

CREATING A GIT REPOSITORY

39       Creating a new Git repository couldn’t be easier: all Git repositories
40       start out empty, and the only thing you need to do is find yourself a
41       subdirectory that you want to use as a working tree - either an empty
42       one for a totally new project, or an existing working tree that you
43       want to import into Git.
44
45       For our first example, we’re going to start a totally new repository
46       from scratch, with no pre-existing files, and we’ll call it
47       git-tutorial. To start up, create a subdirectory for it, change into
48       that subdirectory, and initialize the Git infrastructure with git init:
49
50           $ mkdir git-tutorial
51           $ cd git-tutorial
52           $ git init
53
54       to which Git will reply
55
56           Initialized empty Git repository in .git/
57
58       which is just Git’s way of saying that you haven’t been doing anything
59       strange, and that it will have created a local .git directory setup for
60       your new project. You will now have a .git directory, and you can
61       inspect that with ls. For your new empty project, it should show you
62       three entries, among other things:
63
64       •   a file called HEAD, that has ref: refs/heads/master in it. This is
65           similar to a symbolic link and points at refs/heads/master relative
66           to the HEAD file.
67
68           Don’t worry about the fact that the file that the HEAD link points
69           to doesn’t even exist yet — you haven’t created the commit that
70           will start your HEAD development branch yet.
71
72       •   a subdirectory called objects, which will contain all the objects
73           of your project. You should never have any real reason to look at
74           the objects directly, but you might want to know that these objects
75           are what contains all the real data in your repository.
76
77       •   a subdirectory called refs, which contains references to objects.
78
79       In particular, the refs subdirectory will contain two other
80       subdirectories, named heads and tags respectively. They do exactly what
81       their names imply: they contain references to any number of different
82       heads of development (aka branches), and to any tags that you have
83       created to name specific versions in your repository.
84
85       One note: the special master head is the default branch, which is why
86       the .git/HEAD file was created points to it even if it doesn’t yet
87       exist. Basically, the HEAD link is supposed to always point to the
88       branch you are working on right now, and you always start out expecting
89       to work on the master branch.
90
91       However, this is only a convention, and you can name your branches
92       anything you want, and don’t have to ever even have a master branch. A
93       number of the Git tools will assume that .git/HEAD is valid, though.
94
95           Note
96           An object is identified by its 160-bit SHA-1 hash, aka object name,
97           and a reference to an object is always the 40-byte hex
98           representation of that SHA-1 name. The files in the refs
99           subdirectory are expected to contain these hex references (usually
100           with a final \n at the end), and you should thus expect to see a
101           number of 41-byte files containing these references in these refs
102           subdirectories when you actually start populating your tree.
103
104           Note
105           An advanced user may want to take a look at gitrepository-layout(5)
106           after finishing this tutorial.
107
108       You have now created your first Git repository. Of course, since it’s
109       empty, that’s not very useful, so let’s start populating it with data.
110

POPULATING A GIT REPOSITORY

112       We’ll keep this simple and stupid, so we’ll start off with populating a
113       few trivial files just to get a feel for it.
114
115       Start off with just creating any random files that you want to maintain
116       in your Git repository. We’ll start off with a few bad examples, just
117       to get a feel for how this works:
118
119           $ echo "Hello World" >hello
120           $ echo "Silly example" >example
121
122       you have now created two files in your working tree (aka working
123       directory), but to actually check in your hard work, you will have to
124       go through two steps:
125
126       •   fill in the index file (aka cache) with the information about your
127           working tree state.
128
129       •   commit that index file as an object.
130
131       The first step is trivial: when you want to tell Git about any changes
132       to your working tree, you use the git update-index program. That
133       program normally just takes a list of filenames you want to update, but
134       to avoid trivial mistakes, it refuses to add new entries to the index
135       (or remove existing ones) unless you explicitly tell it that you’re
136       adding a new entry with the --add flag (or removing an entry with the
137       --remove) flag.
138
139       So to populate the index with the two files you just created, you can
140       do
141
142           $ git update-index --add hello example
143
144       and you have now told Git to track those two files.
145
146       In fact, as you did that, if you now look into your object directory,
147       you’ll notice that Git will have added two new objects to the object
148       database. If you did exactly the steps above, you should now be able to
149       do
150
151           $ ls .git/objects/??/*
152
153       and see two files:
154
155           .git/objects/55/7db03de997c86a4a028e1ebd3a1ceb225be238
156           .git/objects/f2/4c74a2e500f5ee1332c86b94199f52b1d1d962
157
158       which correspond with the objects with names of 557db... and f24c7...
159       respectively.
160
161       If you want to, you can use git cat-file to look at those objects, but
162       you’ll have to use the object name, not the filename of the object:
163
164           $ git cat-file -t 557db03de997c86a4a028e1ebd3a1ceb225be238
165
166       where the -t tells git cat-file to tell you what the "type" of the
167       object is. Git will tell you that you have a "blob" object (i.e., just
168       a regular file), and you can see the contents with
169
170           $ git cat-file blob 557db03
171
172       which will print out "Hello World". The object 557db03 is nothing more
173       than the contents of your file hello.
174
175           Note
176           Don’t confuse that object with the file hello itself. The object is
177           literally just those specific contents of the file, and however
178           much you later change the contents in file hello, the object we
179           just looked at will never change. Objects are immutable.
180
181           Note
182           The second example demonstrates that you can abbreviate the object
183           name to only the first several hexadecimal digits in most places.
184
185       Anyway, as we mentioned previously, you normally never actually take a
186       look at the objects themselves, and typing long 40-character hex names
187       is not something you’d normally want to do. The above digression was
188       just to show that git update-index did something magical, and actually
189       saved away the contents of your files into the Git object database.
190
191       Updating the index did something else too: it created a .git/index
192       file. This is the index that describes your current working tree, and
193       something you should be very aware of. Again, you normally never worry
194       about the index file itself, but you should be aware of the fact that
195       you have not actually really "checked in" your files into Git so far,
196       you’ve only told Git about them.
197
198       However, since Git knows about them, you can now start using some of
199       the most basic Git commands to manipulate the files or look at their
200       status.
201
202       In particular, let’s not even check in the two files into Git yet,
203       we’ll start off by adding another line to hello first:
204
205           $ echo "It's a new day for git" >>hello
206
207       and you can now, since you told Git about the previous state of hello,
208       ask Git what has changed in the tree compared to your old index, using
209       the git diff-files command:
210
211           $ git diff-files
212
213       Oops. That wasn’t very readable. It just spit out its own internal
214       version of a diff, but that internal version really just tells you that
215       it has noticed that "hello" has been modified, and that the old object
216       contents it had have been replaced with something else.
217
218       To make it readable, we can tell git diff-files to output the
219       differences as a patch, using the -p flag:
220
221           $ git diff-files -p
222           diff --git a/hello b/hello
223           index 557db03..263414f 100644
224           --- a/hello
225           +++ b/hello
226           @@ -1 +1,2 @@
227            Hello World
228           +It's a new day for git
229
230       i.e. the diff of the change we caused by adding another line to hello.
231
232       In other words, git diff-files always shows us the difference between
233       what is recorded in the index, and what is currently in the working
234       tree. That’s very useful.
235
236       A common shorthand for git diff-files -p is to just write git diff,
237       which will do the same thing.
238
239           $ git diff
240           diff --git a/hello b/hello
241           index 557db03..263414f 100644
242           --- a/hello
243           +++ b/hello
244           @@ -1 +1,2 @@
245            Hello World
246           +It's a new day for git
247

COMMITTING GIT STATE

249       Now, we want to go to the next stage in Git, which is to take the files
250       that Git knows about in the index, and commit them as a real tree. We
251       do that in two phases: creating a tree object, and committing that tree
252       object as a commit object together with an explanation of what the tree
253       was all about, along with information of how we came to that state.
254
255       Creating a tree object is trivial, and is done with git write-tree.
256       There are no options or other input: git write-tree will take the
257       current index state, and write an object that describes that whole
258       index. In other words, we’re now tying together all the different
259       filenames with their contents (and their permissions), and we’re
260       creating the equivalent of a Git "directory" object:
261
262           $ git write-tree
263
264       and this will just output the name of the resulting tree, in this case
265       (if you have done exactly as I’ve described) it should be
266
267           8988da15d077d4829fc51d8544c097def6644dbb
268
269       which is another incomprehensible object name. Again, if you want to,
270       you can use git cat-file -t 8988d... to see that this time the object
271       is not a "blob" object, but a "tree" object (you can also use git
272       cat-file to actually output the raw object contents, but you’ll see
273       mainly a binary mess, so that’s less interesting).
274
275       However — normally you’d never use git write-tree on its own, because
276       normally you always commit a tree into a commit object using the git
277       commit-tree command. In fact, it’s easier to not actually use git
278       write-tree on its own at all, but to just pass its result in as an
279       argument to git commit-tree.
280
281       git commit-tree normally takes several arguments — it wants to know
282       what the parent of a commit was, but since this is the first commit
283       ever in this new repository, and it has no parents, we only need to
284       pass in the object name of the tree. However, git commit-tree also
285       wants to get a commit message on its standard input, and it will write
286       out the resulting object name for the commit to its standard output.
287
288       And this is where we create the .git/refs/heads/master file which is
289       pointed at by HEAD. This file is supposed to contain the reference to
290       the top-of-tree of the master branch, and since that’s exactly what git
291       commit-tree spits out, we can do this all with a sequence of simple
292       shell commands:
293
294           $ tree=$(git write-tree)
295           $ commit=$(echo 'Initial commit' | git commit-tree $tree)
296           $ git update-ref HEAD $commit
297
298       In this case this creates a totally new commit that is not related to
299       anything else. Normally you do this only once for a project ever, and
300       all later commits will be parented on top of an earlier commit.
301
302       Again, normally you’d never actually do this by hand. There is a
303       helpful script called git commit that will do all of this for you. So
304       you could have just written git commit instead, and it would have done
305       the above magic scripting for you.
306

MAKING A CHANGE

308       Remember how we did the git update-index on file hello and then we
309       changed hello afterward, and could compare the new state of hello with
310       the state we saved in the index file?
311
312       Further, remember how I said that git write-tree writes the contents of
313       the index file to the tree, and thus what we just committed was in fact
314       the original contents of the file hello, not the new ones. We did that
315       on purpose, to show the difference between the index state, and the
316       state in the working tree, and how they don’t have to match, even when
317       we commit things.
318
319       As before, if we do git diff-files -p in our git-tutorial project,
320       we’ll still see the same difference we saw last time: the index file
321       hasn’t changed by the act of committing anything. However, now that we
322       have committed something, we can also learn to use a new command: git
323       diff-index.
324
325       Unlike git diff-files, which showed the difference between the index
326       file and the working tree, git diff-index shows the differences between
327       a committed tree and either the index file or the working tree. In
328       other words, git diff-index wants a tree to be diffed against, and
329       before we did the commit, we couldn’t do that, because we didn’t have
330       anything to diff against.
331
332       But now we can do
333
334           $ git diff-index -p HEAD
335
336       (where -p has the same meaning as it did in git diff-files), and it
337       will show us the same difference, but for a totally different reason.
338       Now we’re comparing the working tree not against the index file, but
339       against the tree we just wrote. It just so happens that those two are
340       obviously the same, so we get the same result.
341
342       Again, because this is a common operation, you can also just shorthand
343       it with
344
345           $ git diff HEAD
346
347       which ends up doing the above for you.
348
349       In other words, git diff-index normally compares a tree against the
350       working tree, but when given the --cached flag, it is told to instead
351       compare against just the index cache contents, and ignore the current
352       working tree state entirely. Since we just wrote the index file to
353       HEAD, doing git diff-index --cached -p HEAD should thus return an empty
354       set of differences, and that’s exactly what it does.
355
356           Note
357           git diff-index really always uses the index for its comparisons,
358           and saying that it compares a tree against the working tree is thus
359           not strictly accurate. In particular, the list of files to compare
360           (the "meta-data") always comes from the index file, regardless of
361           whether the --cached flag is used or not. The --cached flag really
362           only determines whether the file contents to be compared come from
363           the working tree or not.
364
365           This is not hard to understand, as soon as you realize that Git
366           simply never knows (or cares) about files that it is not told about
367           explicitly. Git will never go looking for files to compare, it
368           expects you to tell it what the files are, and that’s what the
369           index is there for.
370
371       However, our next step is to commit the change we did, and again, to
372       understand what’s going on, keep in mind the difference between
373       "working tree contents", "index file" and "committed tree". We have
374       changes in the working tree that we want to commit, and we always have
375       to work through the index file, so the first thing we need to do is to
376       update the index cache:
377
378           $ git update-index hello
379
380       (note how we didn’t need the --add flag this time, since Git knew about
381       the file already).
382
383       Note what happens to the different git diff-* versions here. After
384       we’ve updated hello in the index, git diff-files -p now shows no
385       differences, but git diff-index -p HEAD still does show that the
386       current state is different from the state we committed. In fact, now
387       git diff-index shows the same difference whether we use the --cached
388       flag or not, since now the index is coherent with the working tree.
389
390       Now, since we’ve updated hello in the index, we can commit the new
391       version. We could do it by writing the tree by hand again, and
392       committing the tree (this time we’d have to use the -p HEAD flag to
393       tell commit that the HEAD was the parent of the new commit, and that
394       this wasn’t an initial commit any more), but you’ve done that once
395       already, so let’s just use the helpful script this time:
396
397           $ git commit
398
399       which starts an editor for you to write the commit message and tells
400       you a bit about what you have done.
401
402       Write whatever message you want, and all the lines that start with #
403       will be pruned out, and the rest will be used as the commit message for
404       the change. If you decide you don’t want to commit anything after all
405       at this point (you can continue to edit things and update the index),
406       you can just leave an empty message. Otherwise git commit will commit
407       the change for you.
408
409       You’ve now made your first real Git commit. And if you’re interested in
410       looking at what git commit really does, feel free to investigate: it’s
411       a few very simple shell scripts to generate the helpful (?) commit
412       message headers, and a few one-liners that actually do the commit
413       itself (git commit).
414

INSPECTING CHANGES

416       While creating changes is useful, it’s even more useful if you can tell
417       later what changed. The most useful command for this is another of the
418       diff family, namely git diff-tree.
419
420       git diff-tree can be given two arbitrary trees, and it will tell you
421       the differences between them. Perhaps even more commonly, though, you
422       can give it just a single commit object, and it will figure out the
423       parent of that commit itself, and show the difference directly. Thus,
424       to get the same diff that we’ve already seen several times, we can now
425       do
426
427           $ git diff-tree -p HEAD
428
429       (again, -p means to show the difference as a human-readable patch), and
430       it will show what the last commit (in HEAD) actually changed.
431
432           Note
433           Here is an ASCII art by Jon Loeliger that illustrates how various
434           diff-* commands compare things.
435
436                           diff-tree
437                            +----+
438                            |    |
439                            |    |
440                            V    V
441                         +-----------+
442                         | Object DB |
443                         |  Backing  |
444                         |   Store   |
445                         +-----------+
446                           ^    ^
447                           |    |
448                           |    |  diff-index --cached
449                           |    |
450               diff-index  |    V
451                           |  +-----------+
452                           |  |   Index   |
453                           |  |  "cache"  |
454                           |  +-----------+
455                           |    ^
456                           |    |
457                           |    |  diff-files
458                           |    |
459                           V    V
460                         +-----------+
461                         |  Working  |
462                         | Directory |
463                         +-----------+
464
465       More interestingly, you can also give git diff-tree the --pretty flag,
466       which tells it to also show the commit message and author and date of
467       the commit, and you can tell it to show a whole series of diffs.
468       Alternatively, you can tell it to be "silent", and not show the diffs
469       at all, but just show the actual commit message.
470
471       In fact, together with the git rev-list program (which generates a list
472       of revisions), git diff-tree ends up being a veritable fount of
473       changes. You can emulate git log, git log -p, etc. with a trivial
474       script that pipes the output of git rev-list to git diff-tree --stdin,
475       which was exactly how early versions of git log were implemented.
476

TAGGING A VERSION

478       In Git, there are two kinds of tags, a "light" one, and an "annotated
479       tag".
480
481       A "light" tag is technically nothing more than a branch, except we put
482       it in the .git/refs/tags/ subdirectory instead of calling it a head. So
483       the simplest form of tag involves nothing more than
484
485           $ git tag my-first-tag
486
487       which just writes the current HEAD into the .git/refs/tags/my-first-tag
488       file, after which point you can then use this symbolic name for that
489       particular state. You can, for example, do
490
491           $ git diff my-first-tag
492
493       to diff your current state against that tag which at this point will
494       obviously be an empty diff, but if you continue to develop and commit
495       stuff, you can use your tag as an "anchor-point" to see what has
496       changed since you tagged it.
497
498       An "annotated tag" is actually a real Git object, and contains not only
499       a pointer to the state you want to tag, but also a small tag name and
500       message, along with optionally a PGP signature that says that yes, you
501       really did that tag. You create these annotated tags with either the -a
502       or -s flag to git tag:
503
504           $ git tag -s <tagname>
505
506       which will sign the current HEAD (but you can also give it another
507       argument that specifies the thing to tag, e.g., you could have tagged
508       the current mybranch point by using git tag <tagname> mybranch).
509
510       You normally only do signed tags for major releases or things like
511       that, while the light-weight tags are useful for any marking you want
512       to do — any time you decide that you want to remember a certain point,
513       just create a private tag for it, and you have a nice symbolic name for
514       the state at that point.
515

COPYING REPOSITORIES

517       Git repositories are normally totally self-sufficient and relocatable.
518       Unlike CVS, for example, there is no separate notion of "repository"
519       and "working tree". A Git repository normally is the working tree, with
520       the local Git information hidden in the .git subdirectory. There is
521       nothing else. What you see is what you got.
522
523           Note
524           You can tell Git to split the Git internal information from the
525           directory that it tracks, but we’ll ignore that for now: it’s not
526           how normal projects work, and it’s really only meant for special
527           uses. So the mental model of "the Git information is always tied
528           directly to the working tree that it describes" may not be
529           technically 100% accurate, but it’s a good model for all normal
530           use.
531
532       This has two implications:
533
534       •   if you grow bored with the tutorial repository you created (or
535           you’ve made a mistake and want to start all over), you can just do
536           simple
537
538               $ rm -rf git-tutorial
539
540           and it will be gone. There’s no external repository, and there’s no
541           history outside the project you created.
542
543       •   if you want to move or duplicate a Git repository, you can do so.
544           There is git clone command, but if all you want to do is just to
545           create a copy of your repository (with all the full history that
546           went along with it), you can do so with a regular cp -a
547           git-tutorial new-git-tutorial.
548
549           Note that when you’ve moved or copied a Git repository, your Git
550           index file (which caches various information, notably some of the
551           "stat" information for the files involved) will likely need to be
552           refreshed. So after you do a cp -a to create a new copy, you’ll
553           want to do
554
555               $ git update-index --refresh
556
557           in the new repository to make sure that the index file is up to
558           date.
559
560       Note that the second point is true even across machines. You can
561       duplicate a remote Git repository with any regular copy mechanism, be
562       it scp, rsync or wget.
563
564       When copying a remote repository, you’ll want to at a minimum update
565       the index cache when you do this, and especially with other peoples'
566       repositories you often want to make sure that the index cache is in
567       some known state (you don’t know what they’ve done and not yet checked
568       in), so usually you’ll precede the git update-index with a
569
570           $ git read-tree --reset HEAD
571           $ git update-index --refresh
572
573       which will force a total index re-build from the tree pointed to by
574       HEAD. It resets the index contents to HEAD, and then the git
575       update-index makes sure to match up all index entries with the
576       checked-out files. If the original repository had uncommitted changes
577       in its working tree, git update-index --refresh notices them and tells
578       you they need to be updated.
579
580       The above can also be written as simply
581
582           $ git reset
583
584       and in fact a lot of the common Git command combinations can be
585       scripted with the git xyz interfaces. You can learn things by just
586       looking at what the various git scripts do. For example, git reset used
587       to be the above two lines implemented in git reset, but some things
588       like git status and git commit are slightly more complex scripts around
589       the basic Git commands.
590
591       Many (most?) public remote repositories will not contain any of the
592       checked out files or even an index file, and will only contain the
593       actual core Git files. Such a repository usually doesn’t even have the
594       .git subdirectory, but has all the Git files directly in the
595       repository.
596
597       To create your own local live copy of such a "raw" Git repository,
598       you’d first create your own subdirectory for the project, and then copy
599       the raw repository contents into the .git directory. For example, to
600       create your own copy of the Git repository, you’d do the following
601
602           $ mkdir my-git
603           $ cd my-git
604           $ rsync -rL rsync://rsync.kernel.org/pub/scm/git/git.git/ .git
605
606       followed by
607
608           $ git read-tree HEAD
609
610       to populate the index. However, now you have populated the index, and
611       you have all the Git internal files, but you will notice that you don’t
612       actually have any of the working tree files to work on. To get those,
613       you’d check them out with
614
615           $ git checkout-index -u -a
616
617       where the -u flag means that you want the checkout to keep the index up
618       to date (so that you don’t have to refresh it afterward), and the -a
619       flag means "check out all files" (if you have a stale copy or an older
620       version of a checked out tree you may also need to add the -f flag
621       first, to tell git checkout-index to force overwriting of any old
622       files).
623
624       Again, this can all be simplified with
625
626           $ git clone git://git.kernel.org/pub/scm/git/git.git/ my-git
627           $ cd my-git
628           $ git checkout
629
630       which will end up doing all of the above for you.
631
632       You have now successfully copied somebody else’s (mine) remote
633       repository, and checked it out.
634

CREATING A NEW BRANCH

636       Branches in Git are really nothing more than pointers into the Git
637       object database from within the .git/refs/ subdirectory, and as we
638       already discussed, the HEAD branch is nothing but a symlink to one of
639       these object pointers.
640
641       You can at any time create a new branch by just picking an arbitrary
642       point in the project history, and just writing the SHA-1 name of that
643       object into a file under .git/refs/heads/. You can use any filename you
644       want (and indeed, subdirectories), but the convention is that the
645       "normal" branch is called master. That’s just a convention, though, and
646       nothing enforces it.
647
648       To show that as an example, let’s go back to the git-tutorial
649       repository we used earlier, and create a branch in it. You do that by
650       simply just saying that you want to check out a new branch:
651
652           $ git switch -c mybranch
653
654       will create a new branch based at the current HEAD position, and switch
655       to it.
656
657           Note
658           If you make the decision to start your new branch at some other
659           point in the history than the current HEAD, you can do so by just
660           telling git switch what the base of the checkout would be. In other
661           words, if you have an earlier tag or branch, you’d just do
662
663               $ git switch -c mybranch earlier-commit
664
665           and it would create the new branch mybranch at the earlier commit,
666           and check out the state at that time.
667
668       You can always just jump back to your original master branch by doing
669
670           $ git switch master
671
672       (or any other branch-name, for that matter) and if you forget which
673       branch you happen to be on, a simple
674
675           $ cat .git/HEAD
676
677       will tell you where it’s pointing. To get the list of branches you
678       have, you can say
679
680           $ git branch
681
682       which used to be nothing more than a simple script around ls
683       .git/refs/heads. There will be an asterisk in front of the branch you
684       are currently on.
685
686       Sometimes you may wish to create a new branch without actually checking
687       it out and switching to it. If so, just use the command
688
689           $ git branch <branchname> [startingpoint]
690
691       which will simply create the branch, but will not do anything further.
692       You can then later — once you decide that you want to actually develop
693       on that branch — switch to that branch with a regular git switch with
694       the branchname as the argument.
695

MERGING TWO BRANCHES

697       One of the ideas of having a branch is that you do some (possibly
698       experimental) work in it, and eventually merge it back to the main
699       branch. So assuming you created the above mybranch that started out
700       being the same as the original master branch, let’s make sure we’re in
701       that branch, and do some work there.
702
703           $ git switch mybranch
704           $ echo "Work, work, work" >>hello
705           $ git commit -m "Some work." -i hello
706
707       Here, we just added another line to hello, and we used a shorthand for
708       doing both git update-index hello and git commit by just giving the
709       filename directly to git commit, with an -i flag (it tells Git to
710       include that file in addition to what you have done to the index file
711       so far when making the commit). The -m flag is to give the commit log
712       message from the command line.
713
714       Now, to make it a bit more interesting, let’s assume that somebody else
715       does some work in the original branch, and simulate that by going back
716       to the master branch, and editing the same file differently there:
717
718           $ git switch master
719
720       Here, take a moment to look at the contents of hello, and notice how
721       they don’t contain the work we just did in mybranch — because that work
722       hasn’t happened in the master branch at all. Then do
723
724           $ echo "Play, play, play" >>hello
725           $ echo "Lots of fun" >>example
726           $ git commit -m "Some fun." -i hello example
727
728       since the master branch is obviously in a much better mood.
729
730       Now, you’ve got two branches, and you decide that you want to merge the
731       work done. Before we do that, let’s introduce a cool graphical tool
732       that helps you view what’s going on:
733
734           $ gitk --all
735
736       will show you graphically both of your branches (that’s what the --all
737       means: normally it will just show you your current HEAD) and their
738       histories. You can also see exactly how they came to be from a common
739       source.
740
741       Anyway, let’s exit gitk (^Q or the File menu), and decide that we want
742       to merge the work we did on the mybranch branch into the master branch
743       (which is currently our HEAD too). To do that, there’s a nice script
744       called git merge, which wants to know which branches you want to
745       resolve and what the merge is all about:
746
747           $ git merge -m "Merge work in mybranch" mybranch
748
749       where the first argument is going to be used as the commit message if
750       the merge can be resolved automatically.
751
752       Now, in this case we’ve intentionally created a situation where the
753       merge will need to be fixed up by hand, though, so Git will do as much
754       of it as it can automatically (which in this case is just merge the
755       example file, which had no differences in the mybranch branch), and
756       say:
757
758                   Auto-merging hello
759                   CONFLICT (content): Merge conflict in hello
760                   Automatic merge failed; fix conflicts and then commit the result.
761
762       It tells you that it did an "Automatic merge", which failed due to
763       conflicts in hello.
764
765       Not to worry. It left the (trivial) conflict in hello in the same form
766       you should already be well used to if you’ve ever used CVS, so let’s
767       just open hello in our editor (whatever that may be), and fix it up
768       somehow. I’d suggest just making it so that hello contains all four
769       lines:
770
771           Hello World
772           It's a new day for git
773           Play, play, play
774           Work, work, work
775
776       and once you’re happy with your manual merge, just do a
777
778           $ git commit -i hello
779
780       which will very loudly warn you that you’re now committing a merge
781       (which is correct, so never mind), and you can write a small merge
782       message about your adventures in git merge-land.
783
784       After you’re done, start up gitk --all to see graphically what the
785       history looks like. Notice that mybranch still exists, and you can
786       switch to it, and continue to work with it if you want to. The mybranch
787       branch will not contain the merge, but next time you merge it from the
788       master branch, Git will know how you merged it, so you’ll not have to
789       do that merge again.
790
791       Another useful tool, especially if you do not always work in X-Window
792       environment, is git show-branch.
793
794           $ git show-branch --topo-order --more=1 master mybranch
795           * [master] Merge work in mybranch
796            ! [mybranch] Some work.
797           --
798           -  [master] Merge work in mybranch
799           *+ [mybranch] Some work.
800           *  [master^] Some fun.
801
802       The first two lines indicate that it is showing the two branches with
803       the titles of their top-of-the-tree commits, you are currently on
804       master branch (notice the asterisk * character), and the first column
805       for the later output lines is used to show commits contained in the
806       master branch, and the second column for the mybranch branch. Three
807       commits are shown along with their titles. All of them have non blank
808       characters in the first column (* shows an ordinary commit on the
809       current branch, - is a merge commit), which means they are now part of
810       the master branch. Only the "Some work" commit has the plus + character
811       in the second column, because mybranch has not been merged to
812       incorporate these commits from the master branch. The string inside
813       brackets before the commit log message is a short name you can use to
814       name the commit. In the above example, master and mybranch are branch
815       heads. master^ is the first parent of master branch head. Please see
816       gitrevisions(7) if you want to see more complex cases.
817
818           Note
819           Without the --more=1 option, git show-branch would not output the
820           [master^] commit, as [mybranch] commit is a common ancestor of both
821           master and mybranch tips. Please see git-show-branch(1) for
822           details.
823
824           Note
825           If there were more commits on the master branch after the merge,
826           the merge commit itself would not be shown by git show-branch by
827           default. You would need to provide --sparse option to make the
828           merge commit visible in this case.
829
830       Now, let’s pretend you are the one who did all the work in mybranch,
831       and the fruit of your hard work has finally been merged to the master
832       branch. Let’s go back to mybranch, and run git merge to get the
833       "upstream changes" back to your branch.
834
835           $ git switch mybranch
836           $ git merge -m "Merge upstream changes." master
837
838       This outputs something like this (the actual commit object names would
839       be different)
840
841           Updating from ae3a2da... to a80b4aa....
842           Fast-forward (no commit created; -m option ignored)
843            example | 1 +
844            hello   | 1 +
845            2 files changed, 2 insertions(+)
846
847       Because your branch did not contain anything more than what had already
848       been merged into the master branch, the merge operation did not
849       actually do a merge. Instead, it just updated the top of the tree of
850       your branch to that of the master branch. This is often called
851       fast-forward merge.
852
853       You can run gitk --all again to see how the commit ancestry looks like,
854       or run show-branch, which tells you this.
855
856           $ git show-branch master mybranch
857           ! [master] Merge work in mybranch
858            * [mybranch] Merge work in mybranch
859           --
860           -- [master] Merge work in mybranch
861

MERGING EXTERNAL WORK

863       It’s usually much more common that you merge with somebody else than
864       merging with your own branches, so it’s worth pointing out that Git
865       makes that very easy too, and in fact, it’s not that different from
866       doing a git merge. In fact, a remote merge ends up being nothing more
867       than "fetch the work from a remote repository into a temporary tag"
868       followed by a git merge.
869
870       Fetching from a remote repository is done by, unsurprisingly, git
871       fetch:
872
873           $ git fetch <remote-repository>
874
875       One of the following transports can be used to name the repository to
876       download from:
877
878       SSH
879           remote.machine:/path/to/repo.git/ or
880
881           ssh://remote.machine/path/to/repo.git/
882
883           This transport can be used for both uploading and downloading, and
884           requires you to have a log-in privilege over ssh to the remote
885           machine. It finds out the set of objects the other side lacks by
886           exchanging the head commits both ends have and transfers (close to)
887           minimum set of objects. It is by far the most efficient way to
888           exchange Git objects between repositories.
889
890       Local directory
891           /path/to/repo.git/
892
893           This transport is the same as SSH transport but uses sh to run both
894           ends on the local machine instead of running other end on the
895           remote machine via ssh.
896
897       Git Native
898           git://remote.machine/path/to/repo.git/
899
900           This transport was designed for anonymous downloading. Like SSH
901           transport, it finds out the set of objects the downstream side
902           lacks and transfers (close to) minimum set of objects.
903
904       HTTP(S)
905           http://remote.machine/path/to/repo.git/
906
907           Downloader from http and https URL first obtains the topmost commit
908           object name from the remote site by looking at the specified
909           refname under repo.git/refs/ directory, and then tries to obtain
910           the commit object by downloading from repo.git/objects/xx/xxx...
911           using the object name of that commit object. Then it reads the
912           commit object to find out its parent commits and the associate tree
913           object; it repeats this process until it gets all the necessary
914           objects. Because of this behavior, they are sometimes also called
915           commit walkers.
916
917           The commit walkers are sometimes also called dumb transports,
918           because they do not require any Git aware smart server like Git
919           Native transport does. Any stock HTTP server that does not even
920           support directory index would suffice. But you must prepare your
921           repository with git update-server-info to help dumb transport
922           downloaders.
923
924       Once you fetch from the remote repository, you merge that with your
925       current branch.
926
927       However — it’s such a common thing to fetch and then immediately merge,
928       that it’s called git pull, and you can simply do
929
930           $ git pull <remote-repository>
931
932       and optionally give a branch-name for the remote end as a second
933       argument.
934
935           Note
936           You could do without using any branches at all, by keeping as many
937           local repositories as you would like to have branches, and merging
938           between them with git pull, just like you merge between branches.
939           The advantage of this approach is that it lets you keep a set of
940           files for each branch checked out and you may find it easier to
941           switch back and forth if you juggle multiple lines of development
942           simultaneously. Of course, you will pay the price of more disk
943           usage to hold multiple working trees, but disk space is cheap these
944           days.
945
946       It is likely that you will be pulling from the same remote repository
947       from time to time. As a short hand, you can store the remote repository
948       URL in the local repository’s config file like this:
949
950           $ git config remote.linus.url http://www.kernel.org/pub/scm/git/git.git/
951
952       and use the "linus" keyword with git pull instead of the full URL.
953
954       Examples.
955
956        1. git pull linus
957
958        2. git pull linus tag v0.99.1
959
960       the above are equivalent to:
961
962        1. git pull http://www.kernel.org/pub/scm/git/git.git/ HEAD
963
964        2. git pull http://www.kernel.org/pub/scm/git/git.git/ tag v0.99.1
965

HOW DOES THE MERGE WORK?

967       We said this tutorial shows what plumbing does to help you cope with
968       the porcelain that isn’t flushing, but we so far did not talk about how
969       the merge really works. If you are following this tutorial the first
970       time, I’d suggest to skip to "Publishing your work" section and come
971       back here later.
972
973       OK, still with me? To give us an example to look at, let’s go back to
974       the earlier repository with "hello" and "example" file, and bring
975       ourselves back to the pre-merge state:
976
977           $ git show-branch --more=2 master mybranch
978           ! [master] Merge work in mybranch
979            * [mybranch] Merge work in mybranch
980           --
981           -- [master] Merge work in mybranch
982           +* [master^2] Some work.
983           +* [master^] Some fun.
984
985       Remember, before running git merge, our master head was at "Some fun."
986       commit, while our mybranch head was at "Some work." commit.
987
988           $ git switch -C mybranch master^2
989           $ git switch master
990           $ git reset --hard master^
991
992       After rewinding, the commit structure should look like this:
993
994           $ git show-branch
995           * [master] Some fun.
996            ! [mybranch] Some work.
997           --
998           *  [master] Some fun.
999            + [mybranch] Some work.
1000           *+ [master^] Initial commit
1001
1002       Now we are ready to experiment with the merge by hand.
1003
1004       git merge command, when merging two branches, uses 3-way merge
1005       algorithm. First, it finds the common ancestor between them. The
1006       command it uses is git merge-base:
1007
1008           $ mb=$(git merge-base HEAD mybranch)
1009
1010       The command writes the commit object name of the common ancestor to the
1011       standard output, so we captured its output to a variable, because we
1012       will be using it in the next step. By the way, the common ancestor
1013       commit is the "Initial commit" commit in this case. You can tell it by:
1014
1015           $ git name-rev --name-only --tags $mb
1016           my-first-tag
1017
1018       After finding out a common ancestor commit, the second step is this:
1019
1020           $ git read-tree -m -u $mb HEAD mybranch
1021
1022       This is the same git read-tree command we have already seen, but it
1023       takes three trees, unlike previous examples. This reads the contents of
1024       each tree into different stage in the index file (the first tree goes
1025       to stage 1, the second to stage 2, etc.). After reading three trees
1026       into three stages, the paths that are the same in all three stages are
1027       collapsed into stage 0. Also paths that are the same in two of three
1028       stages are collapsed into stage 0, taking the SHA-1 from either stage 2
1029       or stage 3, whichever is different from stage 1 (i.e. only one side
1030       changed from the common ancestor).
1031
1032       After collapsing operation, paths that are different in three trees are
1033       left in non-zero stages. At this point, you can inspect the index file
1034       with this command:
1035
1036           $ git ls-files --stage
1037           100644 7f8b141b65fdcee47321e399a2598a235a032422 0       example
1038           100644 557db03de997c86a4a028e1ebd3a1ceb225be238 1       hello
1039           100644 ba42a2a96e3027f3333e13ede4ccf4498c3ae942 2       hello
1040           100644 cc44c73eb783565da5831b4d820c962954019b69 3       hello
1041
1042       In our example of only two files, we did not have unchanged files so
1043       only example resulted in collapsing. But in real-life large projects,
1044       when only a small number of files change in one commit, this collapsing
1045       tends to trivially merge most of the paths fairly quickly, leaving only
1046       a handful of real changes in non-zero stages.
1047
1048       To look at only non-zero stages, use --unmerged flag:
1049
1050           $ git ls-files --unmerged
1051           100644 557db03de997c86a4a028e1ebd3a1ceb225be238 1       hello
1052           100644 ba42a2a96e3027f3333e13ede4ccf4498c3ae942 2       hello
1053           100644 cc44c73eb783565da5831b4d820c962954019b69 3       hello
1054
1055       The next step of merging is to merge these three versions of the file,
1056       using 3-way merge. This is done by giving git merge-one-file command as
1057       one of the arguments to git merge-index command:
1058
1059           $ git merge-index git-merge-one-file hello
1060           Auto-merging hello
1061           ERROR: Merge conflict in hello
1062           fatal: merge program failed
1063
1064       git merge-one-file script is called with parameters to describe those
1065       three versions, and is responsible to leave the merge results in the
1066       working tree. It is a fairly straightforward shell script, and
1067       eventually calls merge program from RCS suite to perform a file-level
1068       3-way merge. In this case, merge detects conflicts, and the merge
1069       result with conflict marks is left in the working tree.. This can be
1070       seen if you run ls-files --stage again at this point:
1071
1072           $ git ls-files --stage
1073           100644 7f8b141b65fdcee47321e399a2598a235a032422 0       example
1074           100644 557db03de997c86a4a028e1ebd3a1ceb225be238 1       hello
1075           100644 ba42a2a96e3027f3333e13ede4ccf4498c3ae942 2       hello
1076           100644 cc44c73eb783565da5831b4d820c962954019b69 3       hello
1077
1078       This is the state of the index file and the working file after git
1079       merge returns control back to you, leaving the conflicting merge for
1080       you to resolve. Notice that the path hello is still unmerged, and what
1081       you see with git diff at this point is differences since stage 2 (i.e.
1082       your version).
1083

PUBLISHING YOUR WORK

1085       So, we can use somebody else’s work from a remote repository, but how
1086       can you prepare a repository to let other people pull from it?
1087
1088       You do your real work in your working tree that has your primary
1089       repository hanging under it as its .git subdirectory. You could make
1090       that repository accessible remotely and ask people to pull from it, but
1091       in practice that is not the way things are usually done. A recommended
1092       way is to have a public repository, make it reachable by other people,
1093       and when the changes you made in your primary working tree are in good
1094       shape, update the public repository from it. This is often called
1095       pushing.
1096
1097           Note
1098           This public repository could further be mirrored, and that is how
1099           Git repositories at kernel.org are managed.
1100
1101       Publishing the changes from your local (private) repository to your
1102       remote (public) repository requires a write privilege on the remote
1103       machine. You need to have an SSH account there to run a single command,
1104       git-receive-pack.
1105
1106       First, you need to create an empty repository on the remote machine
1107       that will house your public repository. This empty repository will be
1108       populated and be kept up to date by pushing into it later. Obviously,
1109       this repository creation needs to be done only once.
1110
1111           Note
1112           git push uses a pair of commands, git send-pack on your local
1113           machine, and git-receive-pack on the remote machine. The
1114           communication between the two over the network internally uses an
1115           SSH connection.
1116
1117       Your private repository’s Git directory is usually .git, but your
1118       public repository is often named after the project name, i.e.
1119       <project>.git. Let’s create such a public repository for project
1120       my-git. After logging into the remote machine, create an empty
1121       directory:
1122
1123           $ mkdir my-git.git
1124
1125       Then, make that directory into a Git repository by running git init,
1126       but this time, since its name is not the usual .git, we do things
1127       slightly differently:
1128
1129           $ GIT_DIR=my-git.git git init
1130
1131       Make sure this directory is available for others you want your changes
1132       to be pulled via the transport of your choice. Also you need to make
1133       sure that you have the git-receive-pack program on the $PATH.
1134
1135           Note
1136           Many installations of sshd do not invoke your shell as the login
1137           shell when you directly run programs; what this means is that if
1138           your login shell is bash, only .bashrc is read and not
1139           .bash_profile. As a workaround, make sure .bashrc sets up $PATH so
1140           that you can run git-receive-pack program.
1141
1142           Note
1143           If you plan to publish this repository to be accessed over http,
1144           you should do mv my-git.git/hooks/post-update.sample
1145           my-git.git/hooks/post-update at this point. This makes sure that
1146           every time you push into this repository, git update-server-info is
1147           run.
1148
1149       Your "public repository" is now ready to accept your changes. Come back
1150       to the machine you have your private repository. From there, run this
1151       command:
1152
1153           $ git push <public-host>:/path/to/my-git.git master
1154
1155       This synchronizes your public repository to match the named branch head
1156       (i.e. master in this case) and objects reachable from them in your
1157       current repository.
1158
1159       As a real example, this is how I update my public Git repository.
1160       Kernel.org mirror network takes care of the propagation to other
1161       publicly visible machines:
1162
1163           $ git push master.kernel.org:/pub/scm/git/git.git/
1164

PACKING YOUR REPOSITORY

1166       Earlier, we saw that one file under .git/objects/??/ directory is
1167       stored for each Git object you create. This representation is efficient
1168       to create atomically and safely, but not so convenient to transport
1169       over the network. Since Git objects are immutable once they are
1170       created, there is a way to optimize the storage by "packing them
1171       together". The command
1172
1173           $ git repack
1174
1175       will do it for you. If you followed the tutorial examples, you would
1176       have accumulated about 17 objects in .git/objects/??/ directories by
1177       now. git repack tells you how many objects it packed, and stores the
1178       packed file in the .git/objects/pack directory.
1179
1180           Note
1181           You will see two files, pack-*.pack and pack-*.idx, in
1182           .git/objects/pack directory. They are closely related to each
1183           other, and if you ever copy them by hand to a different repository
1184           for whatever reason, you should make sure you copy them together.
1185           The former holds all the data from the objects in the pack, and the
1186           latter holds the index for random access.
1187
1188       If you are paranoid, running git verify-pack command would detect if
1189       you have a corrupt pack, but do not worry too much. Our programs are
1190       always perfect ;-).
1191
1192       Once you have packed objects, you do not need to leave the unpacked
1193       objects that are contained in the pack file anymore.
1194
1195           $ git prune-packed
1196
1197       would remove them for you.
1198
1199       You can try running find .git/objects -type f before and after you run
1200       git prune-packed if you are curious. Also git count-objects would tell
1201       you how many unpacked objects are in your repository and how much space
1202       they are consuming.
1203
1204           Note
1205           git pull is slightly cumbersome for HTTP transport, as a packed
1206           repository may contain relatively few objects in a relatively large
1207           pack. If you expect many HTTP pulls from your public repository you
1208           might want to repack & prune often, or never.
1209
1210       If you run git repack again at this point, it will say "Nothing new to
1211       pack.". Once you continue your development and accumulate the changes,
1212       running git repack again will create a new pack, that contains objects
1213       created since you packed your repository the last time. We recommend
1214       that you pack your project soon after the initial import (unless you
1215       are starting your project from scratch), and then run git repack every
1216       once in a while, depending on how active your project is.
1217
1218       When a repository is synchronized via git push and git pull objects
1219       packed in the source repository are usually stored unpacked in the
1220       destination. While this allows you to use different packing strategies
1221       on both ends, it also means you may need to repack both repositories
1222       every once in a while.
1223

WORKING WITH OTHERS

1225       Although Git is a truly distributed system, it is often convenient to
1226       organize your project with an informal hierarchy of developers. Linux
1227       kernel development is run this way. There is a nice illustration (page
1228       17, "Merges to Mainline") in Randy Dunlap’s presentation[2].
1229
1230       It should be stressed that this hierarchy is purely informal. There is
1231       nothing fundamental in Git that enforces the "chain of patch flow" this
1232       hierarchy implies. You do not have to pull from only one remote
1233       repository.
1234
1235       A recommended workflow for a "project lead" goes like this:
1236
1237        1. Prepare your primary repository on your local machine. Your work is
1238           done there.
1239
1240        2. Prepare a public repository accessible to others.
1241
1242           If other people are pulling from your repository over dumb
1243           transport protocols (HTTP), you need to keep this repository dumb
1244           transport friendly. After git init,
1245           $GIT_DIR/hooks/post-update.sample copied from the standard
1246           templates would contain a call to git update-server-info but you
1247           need to manually enable the hook with mv post-update.sample
1248           post-update. This makes sure git update-server-info keeps the
1249           necessary files up to date.
1250
1251        3. Push into the public repository from your primary repository.
1252
1253        4. git repack the public repository. This establishes a big pack that
1254           contains the initial set of objects as the baseline, and possibly
1255           git prune if the transport used for pulling from your repository
1256           supports packed repositories.
1257
1258        5. Keep working in your primary repository. Your changes include
1259           modifications of your own, patches you receive via e-mails, and
1260           merges resulting from pulling the "public" repositories of your
1261           "subsystem maintainers".
1262
1263           You can repack this private repository whenever you feel like.
1264
1265        6. Push your changes to the public repository, and announce it to the
1266           public.
1267
1268        7. Every once in a while, git repack the public repository. Go back to
1269           step 5. and continue working.
1270
1271       A recommended work cycle for a "subsystem maintainer" who works on that
1272       project and has an own "public repository" goes like this:
1273
1274        1. Prepare your work repository, by running git clone on the public
1275           repository of the "project lead". The URL used for the initial
1276           cloning is stored in the remote.origin.url configuration variable.
1277
1278        2. Prepare a public repository accessible to others, just like the
1279           "project lead" person does.
1280
1281        3. Copy over the packed files from "project lead" public repository to
1282           your public repository, unless the "project lead" repository lives
1283           on the same machine as yours. In the latter case, you can use
1284           objects/info/alternates file to point at the repository you are
1285           borrowing from.
1286
1287        4. Push into the public repository from your primary repository. Run
1288           git repack, and possibly git prune if the transport used for
1289           pulling from your repository supports packed repositories.
1290
1291        5. Keep working in your primary repository. Your changes include
1292           modifications of your own, patches you receive via e-mails, and
1293           merges resulting from pulling the "public" repositories of your
1294           "project lead" and possibly your "sub-subsystem maintainers".
1295
1296           You can repack this private repository whenever you feel like.
1297
1298        6. Push your changes to your public repository, and ask your "project
1299           lead" and possibly your "sub-subsystem maintainers" to pull from
1300           it.
1301
1302        7. Every once in a while, git repack the public repository. Go back to
1303           step 5. and continue working.
1304
1305       A recommended work cycle for an "individual developer" who does not
1306       have a "public" repository is somewhat different. It goes like this:
1307
1308        1. Prepare your work repository, by git clone the public repository of
1309           the "project lead" (or a "subsystem maintainer", if you work on a
1310           subsystem). The URL used for the initial cloning is stored in the
1311           remote.origin.url configuration variable.
1312
1313        2. Do your work in your repository on master branch.
1314
1315        3. Run git fetch origin from the public repository of your upstream
1316           every once in a while. This does only the first half of git pull
1317           but does not merge. The head of the public repository is stored in
1318           .git/refs/remotes/origin/master.
1319
1320        4. Use git cherry origin to see which ones of your patches were
1321           accepted, and/or use git rebase origin to port your unmerged
1322           changes forward to the updated upstream.
1323
1324        5. Use git format-patch origin to prepare patches for e-mail
1325           submission to your upstream and send it out. Go back to step 2. and
1326           continue.
1327

WORKING WITH OTHERS, SHARED REPOSITORY STYLE

1329       If you are coming from a CVS background, the style of cooperation
1330       suggested in the previous section may be new to you. You do not have to
1331       worry. Git supports the "shared public repository" style of cooperation
1332       you are probably more familiar with as well.
1333
1334       See gitcvs-migration(7) for the details.
1335

BUNDLING YOUR WORK TOGETHER

1337       It is likely that you will be working on more than one thing at a time.
1338       It is easy to manage those more-or-less independent tasks using
1339       branches with Git.
1340
1341       We have already seen how branches work previously, with "fun and work"
1342       example using two branches. The idea is the same if there are more than
1343       two branches. Let’s say you started out from "master" head, and have
1344       some new code in the "master" branch, and two independent fixes in the
1345       "commit-fix" and "diff-fix" branches:
1346
1347           $ git show-branch
1348           ! [commit-fix] Fix commit message normalization.
1349            ! [diff-fix] Fix rename detection.
1350             * [master] Release candidate #1
1351           ---
1352            +  [diff-fix] Fix rename detection.
1353            +  [diff-fix~1] Better common substring algorithm.
1354           +   [commit-fix] Fix commit message normalization.
1355             * [master] Release candidate #1
1356           ++* [diff-fix~2] Pretty-print messages.
1357
1358       Both fixes are tested well, and at this point, you want to merge in
1359       both of them. You could merge in diff-fix first and then commit-fix
1360       next, like this:
1361
1362           $ git merge -m "Merge fix in diff-fix" diff-fix
1363           $ git merge -m "Merge fix in commit-fix" commit-fix
1364
1365       Which would result in:
1366
1367           $ git show-branch
1368           ! [commit-fix] Fix commit message normalization.
1369            ! [diff-fix] Fix rename detection.
1370             * [master] Merge fix in commit-fix
1371           ---
1372             - [master] Merge fix in commit-fix
1373           + * [commit-fix] Fix commit message normalization.
1374             - [master~1] Merge fix in diff-fix
1375            +* [diff-fix] Fix rename detection.
1376            +* [diff-fix~1] Better common substring algorithm.
1377             * [master~2] Release candidate #1
1378           ++* [master~3] Pretty-print messages.
1379
1380       However, there is no particular reason to merge in one branch first and
1381       the other next, when what you have are a set of truly independent
1382       changes (if the order mattered, then they are not independent by
1383       definition). You could instead merge those two branches into the
1384       current branch at once. First let’s undo what we just did and start
1385       over. We would want to get the master branch before these two merges by
1386       resetting it to master~2:
1387
1388           $ git reset --hard master~2
1389
1390       You can make sure git show-branch matches the state before those two
1391       git merge you just did. Then, instead of running two git merge commands
1392       in a row, you would merge these two branch heads (this is known as
1393       making an Octopus):
1394
1395           $ git merge commit-fix diff-fix
1396           $ git show-branch
1397           ! [commit-fix] Fix commit message normalization.
1398            ! [diff-fix] Fix rename detection.
1399             * [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
1400           ---
1401             - [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
1402           + * [commit-fix] Fix commit message normalization.
1403            +* [diff-fix] Fix rename detection.
1404            +* [diff-fix~1] Better common substring algorithm.
1405             * [master~1] Release candidate #1
1406           ++* [master~2] Pretty-print messages.
1407
1408       Note that you should not do Octopus just because you can. An octopus is
1409       a valid thing to do and often makes it easier to view the commit
1410       history if you are merging more than two independent changes at the
1411       same time. However, if you have merge conflicts with any of the
1412       branches you are merging in and need to hand resolve, that is an
1413       indication that the development happened in those branches were not
1414       independent after all, and you should merge two at a time, documenting
1415       how you resolved the conflicts, and the reason why you preferred
1416       changes made in one side over the other. Otherwise it would make the
1417       project history harder to follow, not easier.
1418

SEE ALSO

1420       gittutorial(7), gittutorial-2(7), gitcvs-migration(7), git-help(1),
1421       giteveryday(7), The Git User’s Manual[1]
1422

GIT

1424       Part of the git(1) suite
1425

NOTES

1427        1. the Git User Manual
1428           file:///usr/share/doc/git/user-manual.html
1429
1430        2. Randy Dunlap’s presentation
1431           https://web.archive.org/web/20120915203609/http://www.xenotime.net/linux/mentor/linux-mentoring-2006.pdf
1432
1433
1434
1435Git 2.43.0                        11/20/2023               GITCORE-TUTORIAL(7)
Impressum