Tutorial typofix.
[git/git.git] / Documentation / tutorial.txt
CommitLineData
8c7fa247
LT
1A short git tutorial
2====================
3May 2005
4
5
6Introduction
7------------
8
9This is trying to be a short tutorial on setting up and using a git
10archive, mainly because being hands-on and using explicit examples is
11often the best way of explaining what is going on.
12
13In normal life, most people wouldn't use the "core" git programs
14directly, but rather script around them to make them more palatable.
15Understanding the core git stuff may help some people get those scripts
16done, though, and it may also be instructive in helping people
17understand what it is that the higher-level helper scripts are actually
18doing.
19
20The core git is often called "plumbing", with the prettier user
f35ca9ed
LT
21interfaces on top of it called "porcelain". You may not want to use the
22plumbing directly very often, but it can be good to know what the
23plumbing does for when the porcelain isn't flushing...
8c7fa247
LT
24
25
26Creating a git archive
27----------------------
28
29Creating a new git archive couldn't be easier: all git archives start
30out empty, and the only thing you need to do is find yourself a
31subdirectory that you want to use as a working tree - either an empty
32one for a totally new project, or an existing working tree that you want
33to import into git.
34
837eedf4 35For our first example, we're going to start a totally new archive from
8c7fa247
LT
36scratch, with no pre-existing files, and we'll call it "git-tutorial".
37To start up, create a subdirectory for it, change into that
38subdirectory, and initialize the git infrastructure with "git-init-db":
39
40 mkdir git-tutorial
41 cd git-tutorial
42 git-init-db
43
44to which git will reply
45
46 defaulting to local storage area
47
837eedf4 48which is just git's way of saying that you haven't been doing anything
8c7fa247
LT
49strange, and that it will have created a local .git directory setup for
50your new project. You will now have a ".git" directory, and you can
51inspect that with "ls". For your new empty project, ls should show you
52three entries:
53
54 - a symlink called HEAD, pointing to "refs/heads/master"
55
56 Don't worry about the fact that the file that the HEAD link points to
837eedf4 57 doesn't even exist yet - you haven't created the commit that will
8c7fa247
LT
58 start your HEAD development branch yet.
59
60 - a subdirectory called "objects", which will contain all the git SHA1
61 objects of your project. You should never have any real reason to
62 look at the objects directly, but you might want to know that these
63 objects are what contains all the real _data_ in your repository.
64
65 - a subdirectory called "refs", which contains references to objects.
66
67 In particular, the "refs" subdirectory will contain two other
68 subdirectories, named "heads" and "tags" respectively. They do
69 exactly what their names imply: they contain references to any number
70 of different "heads" of development (aka "branches"), and to any
71 "tags" that you have created to name specific versions of your
72 repository.
73
74 One note: the special "master" head is the default branch, which is
75 why the .git/HEAD file was created as a symlink to it even if it
837eedf4 76 doesn't yet exist. Basically, the HEAD link is supposed to always
8c7fa247
LT
77 point to the branch you are working on right now, and you always
78 start out expecting to work on the "master" branch.
79
80 However, this is only a convention, and you can name your branches
81 anything you want, and don't have to ever even _have_ a "master"
82 branch. A number of the git tools will assume that .git/HEAD is
83 valid, though.
84
85 [ Implementation note: an "object" is identified by its 160-bit SHA1
86 hash, aka "name", and a reference to an object is always the 40-byte
87 hex representation of that SHA1 name. The files in the "refs"
88 subdirectory are expected to contain these hex references (usually
89 with a final '\n' at the end), and you should thus expect to see a
90 number of 41-byte files containing these references in this refs
91 subdirectories when you actually start populating your tree ]
92
93You have now created your first git archive. Of course, since it's
94empty, that's not very useful, so let's start populating it with data.
95
96
97 Populating a git archive
98 ------------------------
99
100We'll keep this simple and stupid, so we'll start off with populating a
101few trivial files just to get a feel for it.
102
103Start off with just creating any random files that you want to maintain
104in your git archive. We'll start off with a few bad examples, just to
105get a feel for how this works:
106
107 echo "Hello World" > a
108 echo "Silly example" > b
109
110you have now created two files in your working directory, but to
111actually check in your hard work, you will have to go through two steps:
112
113 - fill in the "cache" aka "index" file with the information about your
114 working directory state
115
116 - commit that index file as an object.
117
118The first step is trivial: when you want to tell git about any changes
119to your working directory, you use the "git-update-cache" program. That
120program normally just takes a list of filenames you want to update, but
121to avoid trivial mistakes, it refuses to add new entries to the cache
122(or remove existing ones) unless you explicitly tell it that you're
123adding a new entry with the "--add" flag (or removing an entry with the
124"--remove") flag.
125
126So to populate the index with the two files you just created, you can do
127
128 git-update-cache --add a b
129
130and you have now told git to track those two files.
131
132In fact, as you did that, if you now look into your object directory,
837eedf4 133you'll notice that git will have added two new objects to the object
8c7fa247
LT
134store. If you did exactly the steps above, you should now be able to do
135
136 ls .git/objects/??/*
137
138and see two files:
139
140 .git/objects/55/7db03de997c86a4a028e1ebd3a1ceb225be238
141 .git/objects/f2/4c74a2e500f5ee1332c86b94199f52b1d1d962
142
143which correspond with the object with SHA1 names of 557db... and f24c7..
144respectively.
145
146If you want to, you can use "git-cat-file" to look at those objects, but
147you'll have to use the object name, not the filename of the object:
148
149 git-cat-file -t 557db03de997c86a4a028e1ebd3a1ceb225be238
150
151where the "-t" tells git-cat-file to tell you what the "type" of the
152object is. Git will tell you that you have a "blob" object (ie just a
153regular file), and you can see the contents with
154
155 git-cat-file "blob" 557db03de997c86a4a028e1ebd3a1ceb225be238
156
157which will print out "Hello World". The object 557db... is nothing
158more than the contents of your file "a".
159
160[ Digression: don't confuse that object with the file "a" itself. The
81bb573e
LT
161 object is literally just those specific _contents_ of the file, and
162 however much you later change the contents in file "a", the object we
163 just looked at will never change. Objects are immutable. ]
8c7fa247
LT
164
165Anyway, as we mentioned previously, you normally never actually take a
166look at the objects themselves, and typing long 40-character hex SHA1
167names is not something you'd normally want to do. The above digression
168was just to show that "git-update-cache" did something magical, and
169actually saved away the contents of your files into the git content
170store.
171
172Updating the cache did something else too: it created a ".git/index"
173file. This is the index that describes your current working tree, and
174something you should be very aware of. Again, you normally never worry
175about the index file itself, but you should be aware of the fact that
176you have not actually really "checked in" your files into git so far,
177you've only _told_ git about them.
178
f35ca9ed 179However, since git knows about them, you can now start using some of the
8c7fa247
LT
180most basic git commands to manipulate the files or look at their status.
181
182In particular, let's not even check in the two files into git yet, we'll
183start off by adding another line to "a" first:
184
185 echo "It's a new day for git" >> a
186
187and you can now, since you told git about the previous state of "a", ask
188git what has changed in the tree compared to your old index, using the
189"git-diff-files" command:
190
191 git-diff-files
192
193oops. That wasn't very readable. It just spit out its own internal
194version of a "diff", but that internal version really just tells you
195that it has noticed that "a" has been modified, and that the old object
196contents it had have been replaced with something else.
197
198To make it readable, we can tell git-diff-files to output the
199differences as a patch, using the "-p" flag:
200
201 git-diff-files -p
202
203which will spit out
204
205 diff --git a/a b/a
206 --- a/a
207 +++ b/a
208 @@ -1 +1,2 @@
209 Hello World
210 +It's a new day for git
211
212ie the diff of the change we caused by adding another line to "a".
213
214In other words, git-diff-files always shows us the difference between
215what is recorded in the index, and what is currently in the working
216tree. That's very useful.
217
ed616049
LT
218A common shorthand for "git-diff-files -p" is to just write
219
220 git diff
221
222which will do the same thing.
223
8c7fa247
LT
224
225 Committing git state
226 --------------------
227
228Now, we want to go to the next stage in git, which is to take the files
229that git knows about in the index, and commit them as a real tree. We do
230that in two phases: creating a "tree" object, and committing that "tree"
231object as a "commit" object together with an explanation of what the
232tree was all about, along with information of how we came to that state.
233
234Creating a tree object is trivial, and is done with "git-write-tree".
235There are no options or other input: git-write-tree will take the
236current index state, and write an object that describes that whole
237index. In other words, we're now tying together all the different
238filenames with their contents (and their permissions), and we're
239creating the equivalent of a git "directory" object:
240
241 git-write-tree
242
243and this will just output the name of the resulting tree, in this case
244(if you have does exactly as I've described) it should be
245
246 3ede4ed7e895432c0a247f09d71a76db53bd0fa4
247
248which is another incomprehensible object name. Again, if you want to,
249you can use "git-cat-file -t 3ede4.." to see that this time the object
250is not a "blob" object, but a "tree" object (you can also use
251git-cat-file to actually output the raw object contents, but you'll see
252mainly a binary mess, so that's less interesting).
253
254However - normally you'd never use "git-write-tree" on its own, because
255normally you always commit a tree into a commit object using the
256"git-commit-tree" command. In fact, it's easier to not actually use
257git-write-tree on its own at all, but to just pass its result in as an
258argument to "git-commit-tree".
259
260"git-commit-tree" normally takes several arguments - it wants to know
261what the _parent_ of a commit was, but since this is the first commit
262ever in this new archive, and it has no parents, we only need to pass in
263the tree ID. However, git-commit-tree also wants to get a commit message
264on its standard input, and it will write out the resulting ID for the
265commit to its standard output.
266
267And this is where we start using the .git/HEAD file. The HEAD file is
268supposed to contain the reference to the top-of-tree, and since that's
269exactly what git-commit-tree spits out, we can do this all with a simple
270shell pipeline:
271
272 echo "Initial commit" | git-commit-tree $(git-write-tree) > .git/HEAD
273
274which will say:
275
276 Committing initial tree 3ede4ed7e895432c0a247f09d71a76db53bd0fa4
277
278just to warn you about the fact that it created a totally new commit
279that is not related to anything else. Normally you do this only _once_
280for a project ever, and all later commits will be parented on top of an
281earlier commit, and you'll never see this "Committing initial tree"
282message ever again.
283
ed616049
LT
284Again, normally you'd never actually do this by hand. There is a
285helpful script called "git commit" that will do all of this for you. So
286you could have just writtten
287
288 git commit
289
290instead, and it would have done the above magic scripting for you.
291
8c7fa247
LT
292
293 Making a change
294 ---------------
295
296Remember how we did the "git-update-cache" on file "a" and then we
837eedf4 297changed "a" afterward, and could compare the new state of "a" with the
8c7fa247
LT
298state we saved in the index file?
299
300Further, remember how I said that "git-write-tree" writes the contents
301of the _index_ file to the tree, and thus what we just committed was in
302fact the _original_ contents of the file "a", not the new ones. We did
303that on purpose, to show the difference between the index state, and the
304state in the working directory, and how they don't have to match, even
305when we commit things.
306
307As before, if we do "git-diff-files -p" in our git-tutorial project,
308we'll still see the same difference we saw last time: the index file
309hasn't changed by the act of committing anything. However, now that we
310have committed something, we can also learn to use a new command:
311"git-diff-cache".
312
313Unlike "git-diff-files", which showed the difference between the index
314file and the working directory, "git-diff-cache" shows the differences
a7b20909
LT
315between a committed _tree_ and either the the index file or the working
316directory. In other words, git-diff-cache wants a tree to be diffed
317against, and before we did the commit, we couldn't do that, because we
318didn't have anything to diff against.
8c7fa247
LT
319
320But now we can do
321
322 git-diff-cache -p HEAD
323
324(where "-p" has the same meaning as it did in git-diff-files), and it
325will show us the same difference, but for a totally different reason.
a7b20909
LT
326Now we're comparing the working directory not against the index file,
327but against the tree we just wrote. It just so happens that those two
328are obviously the same, so we get the same result.
329
ed616049
LT
330Again, because this is a common operation, you can also just shorthand
331it with
332
333 git diff HEAD
334
335which ends up doing the above for you.
336
a7b20909
LT
337In other words, "git-diff-cache" normally compares a tree against the
338working directory, but when given the "--cached" flag, it is told to
339instead compare against just the index cache contents, and ignore the
340current working directory state entirely. Since we just wrote the index
341file to HEAD, doing "git-diff-cache --cached -p HEAD" should thus return
342an empty set of differences, and that's exactly what it does.
343
344[ Digression: "git-diff-cache" really always uses the index for its
345 comparisons, and saying that it compares a tree against the working
346 directory is thus not strictly accurate. In particular, the list of
347 files to compare (the "meta-data") _always_ comes from the index file,
348 regardless of whether the --cached flag is used or not. The --cached
349 flag really only determines whether the file _contents_ to be compared
350 come from the working directory or not.
351
352 This is not hard to understand, as soon as you realize that git simply
353 never knows (or cares) about files that it is not told about
354 explicitly. Git will never go _looking_ for files to compare, it
355 expects you to tell it what the files are, and that's what the index
356 is there for. ]
8c7fa247
LT
357
358However, our next step is to commit the _change_ we did, and again, to
837eedf4 359understand what's going on, keep in mind the difference between "working
8c7fa247
LT
360directory contents", "index file" and "committed tree". We have changes
361in the working directory that we want to commit, and we always have to
362work through the index file, so the first thing we need to do is to
363update the index cache:
364
365 git-update-cache a
366
367(note how we didn't need the "--add" flag this time, since git knew
368about the file already).
369
370Note what happens to the different git-diff-xxx versions here. After
371we've updated "a" in the index, "git-diff-files -p" now shows no
372differences, but "git-diff-cache -p HEAD" still _does_ show that the
373current state is different from the state we committed. In fact, now
374"git-diff-cache" shows the same difference whether we use the "--cached"
375flag or not, since now the index is coherent with the working directory.
376
377Now, since we've updated "a" in the index, we can commit the new
ed616049
LT
378version. We could do it by writing the tree by hand again, and
379committing the tree (this time we'd have to use the "-p HEAD" flag to
380tell commit that the HEAD was the _parent_ of the new commit, and that
381this wasn't an initial commit any more), but you've done that once
382already, so let's just use the helpful script this time:
8c7fa247 383
81bb573e 384 git commit
8c7fa247 385
ed616049
LT
386which starts an editor for you to write the commit message and tells you
387a bit about what you're doing.
388
8c7fa247
LT
389Write whatever message you want, and all the lines that start with '#'
390will be pruned out, and the rest will be used as the commit message for
391the change. If you decide you don't want to commit anything after all at
392this point (you can continue to edit things and update the cache), you
393can just leave an empty message. Otherwise git-commit-script will commit
394the change for you.
395
8c7fa247
LT
396You've now made your first real git commit. And if you're interested in
397looking at what git-commit-script really does, feel free to investigate:
398it's a few very simple shell scripts to generate the helpful (?) commit
399message headers, and a few one-liners that actually do the commit itself.
400
401
402 Checking it out
403 ---------------
404
405While creating changes is useful, it's even more useful if you can tell
406later what changed. The most useful command for this is another of the
407"diff" family, namely "git-diff-tree".
408
409git-diff-tree can be given two arbitrary trees, and it will tell you the
410differences between them. Perhaps even more commonly, though, you can
411give it just a single commit object, and it will figure out the parent
412of that commit itself, and show the difference directly. Thus, to get
413the same diff that we've already seen several times, we can now do
414
415 git-diff-tree -p HEAD
416
417(again, "-p" means to show the difference as a human-readable patch),
418and it will show what the last commit (in HEAD) actually changed.
419
420More interestingly, you can also give git-diff-tree the "-v" flag, which
421tells it to also show the commit message and author and date of the
422commit, and you can tell it to show a whole series of diffs.
423Alternatively, you can tell it to be "silent", and not show the diffs at
424all, but just show the actual commit message.
425
426In fact, together with the "git-rev-list" program (which generates a
427list of revisions), git-diff-tree ends up being a veritable fount of
428changes. A trivial (but very useful) script called "git-whatchanged" is
429included with git which does exactly this, and shows a log of recent
430activity.
431
81bb573e 432To see the whole history of our pitiful little git-tutorial project, you
8c7fa247
LT
433can do
434
81bb573e
LT
435 git log
436
437which shows just the log messages, or if we want to see the log together
cc29f732 438with the associated patches use the more complex (and much more
81bb573e
LT
439powerful)
440
837eedf4 441 git-whatchanged -p --root
8c7fa247 442
81bb573e
LT
443and you will see exactly what has changed in the repository over its
444short history.
445
446[ Side note: the "--root" flag is a flag to git-diff-tree to tell it to
447 show the initial aka "root" commit too. Normally you'd probably not
448 want to see the initial import diff, but since the tutorial project
449 was started from scratch and is so small, we use it to make the result
450 a bit more interesting ]
8c7fa247 451
837eedf4 452With that, you should now be having some inkling of what git does, and
8c7fa247
LT
453can explore on your own.
454
f35ca9ed 455
3eb5128a
JH
456[ Side note: most likely, you are not directly using the core
457 git Plumbing commands, but using Porcelain like Cogito on top
458 of it. Cogito works a bit differently and you usually do not
459 have to run "git-update-cache" yourself for changed files (you
460 do tell underlying git about additions and removals via
461 "cg-add" and "cg-rm" commands). Just before you make a commit
462 with "cg-commit", Cogito figures out which files you modified,
463 and runs "git-update-cache" on them for you. ]
464
465
466 Tagging a version
467 -----------------
468
469In git, there's two kinds of tags, a "light" one, and a "signed tag".
470
471A "light" tag is technically nothing more than a branch, except we put
472it in the ".git/refs/tags/" subdirectory instead of calling it a "head".
473So the simplest form of tag involves nothing more than
474
a7333f9e 475 git tag my-first-tag
3eb5128a 476
a7333f9e
LT
477which just writes the current HEAD into the .git/refs/tags/my-first-tag
478file, after which point you can then use this symbolic name for that
479particular state. You can, for example, do
3eb5128a
JH
480
481 git diff my-first-tag
482
483to diff your current state against that tag (which at this point will
484obviously be an empty diff, but if you continue to develop and commit
485stuff, you can use your tag as a "anchor-point" to see what has changed
486since you tagged it.
487
488A "signed tag" is actually a real git object, and contains not only a
489pointer to the state you want to tag, but also a small tag name and
490message, along with a PGP signature that says that yes, you really did
a7333f9e 491that tag. You create these signed tags with the "-s" flag to "git tag":
3eb5128a 492
a7333f9e 493 git tag -s <tagname>
3eb5128a
JH
494
495which will sign the current HEAD (but you can also give it another
496argument that specifies the thing to tag, ie you could have tagged the
497current "mybranch" point by using "git tag <tagname> mybranch").
498
499You normally only do signed tags for major releases or things
500like that, while the light-weight tags are useful for any marking you
501want to do - any time you decide that you want to remember a certain
502point, just create a private tag for it, and you have a nice symbolic
503name for the state at that point.
504
505
cc29f732 506 Copying archives
f35ca9ed
LT
507 -----------------
508
cc29f732 509Git archives are normally totally self-sufficient, and it's worth noting
f35ca9ed
LT
510that unlike CVS, for example, there is no separate notion of
511"repository" and "working tree". A git repository normally _is_ the
512working tree, with the local git information hidden in the ".git"
513subdirectory. There is nothing else. What you see is what you got.
514
515[ Side note: you can tell git to split the git internal information from
516 the directory that it tracks, but we'll ignore that for now: it's not
517 how normal projects work, and it's really only meant for special uses.
518 So the mental model of "the git information is always tied directly to
519 the working directory that it describes" may not be technically 100%
520 accurate, but it's a good model for all normal use ]
521
522This has two implications:
523
524 - if you grow bored with the tutorial archive you created (or you've
525 made a mistake and want to start all over), you can just do simple
526
527 rm -rf git-tutorial
528
529 and it will be gone. There's no external repository, and there's no
530 history outside of the project you created.
531
532 - if you want to move or duplicate a git archive, you can do so. There
e7c1ca42
JH
533 is "git clone" command, but if all you want to do is just to
534 create a copy of your archive (with all the full history that
535 went along with it), you can do so with a regular
536 "cp -a git-tutorial new-git-tutorial".
f35ca9ed
LT
537
538 Note that when you've moved or copied a git archive, your git index
539 file (which caches various information, notably some of the "stat"
540 information for the files involved) will likely need to be refreshed.
541 So after you do a "cp -a" to create a new copy, you'll want to do
542
543 git-update-cache --refresh
544
545 to make sure that the index file is up-to-date in the new one.
546
547Note that the second point is true even across machines. You can
548duplicate a remote git archive with _any_ regular copy mechanism, be it
549"scp", "rsync" or "wget".
550
551When copying a remote repository, you'll want to at a minimum update the
552index cache when you do this, and especially with other peoples
553repositories you often want to make sure that the index cache is in some
554known state (you don't know _what_ they've done and not yet checked in),
555so usually you'll precede the "git-update-cache" with a
556
ce30a4b6 557 git-read-tree --reset HEAD
f35ca9ed
LT
558 git-update-cache --refresh
559
ce30a4b6
LT
560which will force a total index re-build from the tree pointed to by HEAD
561(it resets the index contents to HEAD, and then the git-update-cache
562makes sure to match up all index entries with the checked-out files).
f35ca9ed 563
ce30a4b6
LT
564The above can also be written as simply
565
566 git reset
567
568and in fact a lot of the common git command combinations can be scripted
569with the "git xyz" interfaces, and you can learn things by just looking
570at what the git-*-script scripts do ("git reset" is the above two lines
571implemented in "git-reset-script", but some things like "git status" and
572"git commit" are slightly more complex scripts around the basic git
573commands).
574
575NOTE! Many (most?) public remote repositories will not contain any of
576the checked out files or even an index file, and will _only_ contain the
577actual core git files. Such a repository usually doesn't even have the
f35ca9ed 578".git" subdirectory, but has all the git files directly in the
ce30a4b6 579repository.
f35ca9ed
LT
580
581To create your own local live copy of such a "raw" git repository, you'd
cc29f732 582first create your own subdirectory for the project, and then copy the
f35ca9ed
LT
583raw repository contents into the ".git" directory. For example, to
584create your own copy of the git repository, you'd do the following
585
586 mkdir my-git
587 cd my-git
e7c1ca42 588 rsync -rL rsync://rsync.kernel.org/pub/scm/git/git.git/ my-git .git
f35ca9ed
LT
589
590followed by
591
592 git-read-tree HEAD
593
594to populate the index. However, now you have populated the index, and
595you have all the git internal files, but you will notice that you don't
596actually have any of the _working_directory_ files to work on. To get
597those, you'd check them out with
598
599 git-checkout-cache -u -a
600
601where the "-u" flag means that you want the checkout to keep the index
cc29f732 602up-to-date (so that you don't have to refresh it afterward), and the
e7c1ca42 603"-a" flag means "check out all files" (if you have a stale copy or an
f35ca9ed 604older version of a checked out tree you may also need to add the "-f"
e7c1ca42 605flag first, to tell git-checkout-cache to _force_ overwriting of any old
f35ca9ed
LT
606files).
607
ed616049
LT
608Again, this can all be simplified with
609
e7c1ca42 610 git clone rsync://rsync.kernel.org/pub/scm/git/git.git/ my-git
ed616049
LT
611 cd my-git
612 git checkout
613
614which will end up doing all of the above for you.
615
cc29f732 616You have now successfully copied somebody else's (mine) remote
f35ca9ed
LT
617repository, and checked it out.
618
ed616049
LT
619
620 Creating a new branch
621 ---------------------
622
623Branches in git are really nothing more than pointers into the git
a7333f9e 624object space from within the ".git/refs/" subdirectory, and as we
ed616049
LT
625already discussed, the HEAD branch is nothing but a symlink to one of
626these object pointers.
627
628You can at any time create a new branch by just picking an arbitrary
629point in the project history, and just writing the SHA1 name of that
630object into a file under .git/refs/heads/. You can use any filename you
631want (and indeed, subdirectories), but the convention is that the
632"normal" branch is called "master". That's just a convention, though,
633and nothing enforces it.
634
635To show that as an example, let's go back to the git-tutorial archive we
a7333f9e
LT
636used earlier, and create a branch in it. You do that by simply just
637saying that you want to check out a new branch:
ed616049 638
a7333f9e 639 git checkout -b mybranch
ed616049 640
a7333f9e
LT
641will create a new branch based at the current HEAD position, and switch
642to it.
ed616049 643
a7333f9e
LT
644[ Side note: if you make the decision to start your new branch at some
645 other point in the history than the current HEAD, you can do so by
646 just telling "git checkout" what the base of the checkout would be.
647 In other words, if you have an earlier tag or branch, you'd just do
ed616049 648
a7333f9e 649 git checkout -b mybranch earlier-branch
ed616049 650
a7333f9e
LT
651 and it would create the new branch "mybranch" at the earlier point,
652 and check out the state at that time. ]
ed616049
LT
653
654You can always just jump back to your original "master" branch by doing
655
656 git checkout master
657
a7333f9e
LT
658(or any other branch-name, for that matter) and if you forget which
659branch you happen to be on, a simple
ed616049
LT
660
661 ls -l .git/HEAD
662
663will tell you where it's pointing.
664
a7333f9e
LT
665NOTE! Sometimes you may wish to create a new branch _without_ actually
666checking it out and switching to it. If so, just use the command
667
668 git branch <branchname> [startingpoint]
669
670which will simply _create_ the branch, but will not do anything further.
671You can then later - once you decide that you want to actually develop
672on that branch - switch to that branch with a regular "git checkout"
673with the branchname as the argument.
674
ed616049
LT
675
676 Merging two branches
677 --------------------
678
679One of the ideas of having a branch is that you do some (possibly
680experimental) work in it, and eventually merge it back to the main
681branch. So assuming you created the above "mybranch" that started out
682being the same as the original "master" branch, let's make sure we're in
683that branch, and do some work there.
684
685 git checkout mybranch
686 echo "Work, work, work" >> a
687 git commit a
688
689Here, we just added another line to "a", and we used a shorthand for
690both going a "git-update-cache a" and "git commit" by just giving the
691filename directly to "git commit".
692
693Now, to make it a bit more interesting, let's assume that somebody else
694does some work in the original branch, and simulate that by going back
695to the master branch, and editing the same file differently there:
696
697 git checkout master
698
699Here, take a moment to look at the contents of "a", and notice how they
700don't contain the work we just did in "mybranch" - because that work
701hasn't happened in the "master" branch at all. Then do
702
703 echo "Play, play, play" >> a
704 echo "Lots of fun" >> b
705 git commit a b
706
707since the master branch is obviously in a much better mood.
708
709Now, you've got two branches, and you decide that you want to merge the
710work done. Before we do that, let's introduce a cool graphical tool that
711helps you view what's going on:
712
713 gitk --all
714
715will show you graphically both of your branches (that's what the "--all"
716means: normally it will just show you your current HEAD) and their
717histories. You can also see exactly how they came to be from a common
718source.
719
720Anyway, let's exit gitk (^Q or the File menu), and decide that we want
721to merge the work we did on the "mybranch" branch into the "master"
722branch (which is currently our HEAD too). To do that, there's a nice
723script called "git resolve", which wants to know which branches you want
724to resolve and what the merge is all about:
725
726 git resolve HEAD mybranch "Merge work in mybranch"
727
728where the third argument is going to be used as the commit message if
729the merge can be resolved automatically.
730
731Now, in this case we've intentionally created a situation where the
732merge will need to be fixed up by hand, though, so git will do as much
733of it as it can automatically (which in this case is just merge the "b"
734file, which had no differences in the "mybranch" branch), and say:
735
736 Simple merge failed, trying Automatic merge
737 Auto-merging a.
738 merge: warning: conflicts during merge
739 ERROR: Merge conflict in a.
740 fatal: merge program failed
741 Automatic merge failed, fix up by hand
742
743which is way too verbose, but it basically tells you that it failed the
744really trivial merge ("Simple merge") and did an "Automatic merge"
745instead, but that too failed due to conflicts in "a".
746
747Not to worry. It left the (trivial) conflict in "a" in the same form you
748should already be well used to if you've ever used CVS, so let's just
749open "a" in our editor (whatever that may be), and fix it up somehow.
750I'd suggest just making it so that "a" contains all four lines:
751
752 Hello World
753 It's a new day for git
754 Play, play, play
755 Work, work, work
756
757and once you're happy with your manual merge, just do a
758
759 git commit a
760
761which will very loudly warn you that you're now committing a merge
762(which is correct, so never mind), and you can write a small merge
763message about your adventures in git-merge-land.
764
765After you're done, start up "gitk --all" to see graphically what the
f3157244 766history looks like. Notice that "mybranch" still exists, and you can
ed616049
LT
767switch to it, and continue to work with it if you want to. The
768"mybranch" branch will not contain the merge, but next time you merge it
769from the "master" branch, git will know how you merged it, so you'll not
770have to do _that_ merge again.
771
772
773 Merging external work
774 ---------------------
775
776It's usually much more common that you merge with somebody else than
777merging with your own branches, so it's worth pointing out that git
778makes that very easy too, and in fact, it's not that different from
779doing a "git resolve". In fact, a remote merge ends up being nothing
780more than "fetch the work from a remote repository into a temporary tag"
781followed by a "git resolve".
782
783It's such a common thing to do that it's called "git pull", and you can
784simply do
785
786 git pull <remote-repository>
787
788and optionally give a branch-name for the remote end as a second
789argument.
790
3eb5128a
JH
791The "remote" repository can even be on the same machine. One of
792the following notations can be used to name the repository to
793pull from:
ed616049 794
3eb5128a
JH
795 Rsync URL
796 rsync://remote.machine/path/to/repo.git/
ed616049 797
3eb5128a
JH
798 HTTP(s) URL
799 http://remote.machine/path/to/repo.git/
ed616049 800
3eb5128a
JH
801 GIT URL
802 git://remote.machine/path/to/repo.git/
803 remote.machine:/path/to/repo.git/
ed616049 804
3eb5128a
JH
805 Local directory
806 /path/to/repo.git/
ed616049 807
3eb5128a
JH
808[ Side Note: currently, HTTP transport is slightly broken in
809 that when the remote repository is "packed" they do not always
810 work. But we have not talked about packing repository yet, so
811 let's not worry too much about it for now. ]
ed616049 812
3eb5128a
JH
813[ Digression: you could do without using any branches at all, by
814 keeping as many local repositories as you would like to have
815 branches, and merging between them with "git pull", just like
816 you merge between branches. The advantage of this approach is
817 that it lets you keep set of files for each "branch" checked
818 out and you may find it easier to switch back and forth if you
819 juggle multiple lines of development simultaneously. Of
820 course, you will pay the price of more disk usage to hold
821 multiple working trees, but disk space is cheap these days. ]
ed616049 822
0c04094b
JH
823It is likely that you will be pulling from the same remote
824repository from time to time. As a short hand, you can store
825the remote repository URL in a file under .git/branches/
826directory, like this:
827
828 mkdir -p .git/branches
829 echo rsync://kernel.org/pub/scm/git/git.git/ \
830 >.git/branches/linus
831
832and use the filenae to "git pull" instead of the full URL.
833The contents of a file under .git/branches can even be a prefix
834of a full URL, like this:
835
836 echo rsync://kernel.org/pub/.../jgarzik/
837 >.git/branches/jgarzik
838
839Examples.
840
841 (1) git pull linus
842 (2) git pull linus tag v0.99.1
843 (3) git pull jgarzik/netdev-2.6.git/ e100
844
845the above are equivalent to:
846
847 (1) git pull rsync://kernel.org/pub/scm/git/git.git/ HEAD
848 (2) git pull rsync://kernel.org/pub/scm/git/git.git/ tag v0.99.1
849 (3) git pull rsync://kernel.org/pub/.../jgarzik/netdev-2.6.git e100
850
e7c1ca42
JH
851
852 Publishing your work
853 --------------------
854
3eb5128a
JH
855So we can use somebody else's work from a remote repository; but
856how can _you_ prepare a repository to let other people pull from
857it?
e7c1ca42 858
3eb5128a 859Your do your real work in your working directory that has your
e7c1ca42 860primary repository hanging under it as its ".git" subdirectory.
3eb5128a
JH
861You _could_ make that repository accessible remotely and ask
862people to pull from it, but in practice that is not the way
863things are usually done. A recommended way is to have a public
864repository, make it reachable by other people, and when the
865changes you made in your primary working directory are in good
866shape, update the public repository from it. This is often
867called "pushing".
e7c1ca42
JH
868
869[ Side note: this public repository could further be mirrored,
870 and that is how kernel.org git repositories are done. ]
871
3eb5128a
JH
872Publishing the changes from your local (private) repository to
873your remote (public) repository requires a write privilege on
874the remote machine. You need to have an SSH account there to
875run a single command, "git-receive-pack".
e7c1ca42 876
3eb5128a
JH
877First, you need to create an empty repository on the remote
878machine that will house your public repository. This empty
879repository will be populated and be kept up-to-date by pushing
880into it later. Obviously, this repository creation needs to be
e7c1ca42
JH
881done only once.
882
3eb5128a
JH
883[ Digression: "git push" uses a pair of programs,
884 "git-send-pack" on your local machine, and "git-receive-pack"
885 on the remote machine. The communication between the two over
886 the network internally uses an SSH connection. ]
887
e7c1ca42 888Your private repository's GIT directory is usually .git, but
3eb5128a
JH
889your public repository is often named after the project name,
890i.e. "<project>.git". Let's create such a public repository for
891project "my-git". After logging into the remote machine, create
892an empty directory:
e7c1ca42
JH
893
894 mkdir my-git.git
895
3eb5128a
JH
896Then, make that directory into a GIT repository by running
897git-init-db, but this time, since it's name is not the usual
898".git", we do things slightly differently:
e7c1ca42
JH
899
900 GIT_DIR=my-git.git git-init-db
901
902Make sure this directory is available for others you want your
3eb5128a
JH
903changes to be pulled by via the transport of your choice. Also
904you need to make sure that you have the "git-receive-pack"
905program on the $PATH.
906
907[ Side note: many installations of sshd do not invoke your shell
908 as the login shell when you directly run programs; what this
909 means is that if your login shell is bash, only .bashrc is
910 read and not .bash_profile. As a workaround, make sure
911 .bashrc sets up $PATH so that you can run 'git-receive-pack'
912 program. ]
913
914Your "public repository" is now ready to accept your changes.
915Come back to the machine you have your private repository. From
e7c1ca42
JH
916there, run this command:
917
918 git push <public-host>:/path/to/my-git.git master
919
920This synchronizes your public repository to match the named
3eb5128a
JH
921branch head (i.e. "master" in this case) and objects reachable
922from them in your current repository.
e7c1ca42
JH
923
924As a real example, this is how I update my public git
925repository. Kernel.org mirror network takes care of the
3eb5128a 926propagation to other publicly visible machines:
e7c1ca42
JH
927
928 git push master.kernel.org:/pub/scm/git/git.git/
929
930
3eb5128a
JH
931[ Digression: your GIT "public" repository people can pull from
932 is different from a public CVS repository that lets read-write
933 access to multiple developers. It is a copy of _your_ primary
934 repository published for others to use, and you should not
935 push into it from more than one repository (this means, not
936 just disallowing other developers to push into it, but also
937 you should push into it from a single repository of yours).
938 Sharing the result of work done by multiple people are always
939 done by pulling (i.e. fetching and merging) from public
940 repositories of those people. Typically this is done by the
941 "project lead" person, and the resulting repository is
942 published as the public repository of the "project lead" for
943 everybody to base further changes on. ]
944
945
946 Packing your repository
947 -----------------------
948
949Earlier, we saw that one file under .git/objects/??/ directory
950is stored for each git object you create. This representation
951is convenient and efficient to create atomically and safely, but
952not so to transport over the network. Since git objects are
953immutable once they are created, there is a way to optimize the
954storage by "packing them together". The command
955
956 git repack
957
958will do it for you. If you followed the tutorial examples, you
959would have accumulated about 17 objects in .git/objects/??/
960directories by now. "git repack" tells you how many objects it
961packed, and stores the packed file in .git/objects/pack
962directory.
963
964[ Side Note: you will see two files, pack-*.pack and pack-*.idx,
965 in .git/objects/pack directory. They are closely related to
966 each other, and if you ever copy them by hand to a different
967 repository for whatever reason, you should make sure you copy
968 them together. The former holds all the data from the objects
969 in the pack, and the latter holds the index for random
970 access. ]
971
972If you are paranoid, running "git-verify-pack" command would
973detect if you have a corrupt pack, but do not worry too much.
974Our programs are always perfect ;-).
975
976Once you have packed objects, you do not need to leave the
977unpacked objects that are contained in the pack file anymore.
978
979 git prune-packed
980
981would remove them for you.
982
983You can try running "find .git/objects -type f" before and after
984you run "git prune-packed" if you are curious.
985
986[ Side Note: as we already mentioned, "git pull" is broken for
987 some transports dealing with packed repositories right now, so
988 do not run "git prune-packed" if you plan to give "git pull"
989 access via HTTP transport for now. ]
990
991If you run "git repack" again at this point, it will say
992"Nothing to pack". Once you continue your development and
993accumulate the changes, running "git repack" again will create a
994new pack, that contains objects created since you packed your
995archive the last time. We recommend that you pack your project
996soon after the initial import (unless you are starting your
997project from scratch), and then run "git repack" every once in a
998while, depending on how active your project is.
999
1000When a repository is synchronized via "git push" and "git pull",
1001objects packed in the source repository is usually stored
1002unpacked in the destination, unless rsync transport is used.
1003
1004
1005 Working with Others
1006 -------------------
1007
a232a132
JH
1008Although git is a truly distributed system, it is often
1009convenient to organize your project with an informal hierarchy
1010of developers. Linux kernel development is run this way. There
1011is a nice illustration (page 17, "Merges to Mainline") in Randy
1012Dunlap's presentation (http://tinyurl.com/a2jdg).
1013
1014It should be stressed that this hierarchy is purely "informal".
1015There is nothing fundamental in git that enforces the "chain of
1016patch flow" this hierarchy implies. You do not have to pull
1017from only one remote repository.
1018
1019
1020A recommended workflow for a "project lead" goes like this:
3eb5128a
JH
1021
1022 (1) Prepare your primary repository on your local machine. Your
1023 work is done there.
1024
1025 (2) Prepare a public repository accessible to others.
1026
1027 (3) Push into the public repository from your primary
1028 repository.
1029
1030 (4) "git repack" the public repository. This establishes a big
a232a132
JH
1031 pack that contains the initial set of objects as the
1032 baseline, and possibly "git prune-packed" if the transport
1033 used for pulling from your repository supports packed
1034 repositories.
3eb5128a 1035
a232a132
JH
1036 (5) Keep working in your primary repository. Your changes
1037 include modifications of your own, patches you receive via
1038 e-mails, and merges resulting from pulling the "public"
1039 repositories of your "subsystem maintainers".
3eb5128a
JH
1040
1041 You can repack this private repository whenever you feel
1042 like.
1043
a232a132
JH
1044 (6) Push your changes to the public repository, and announce it
1045 to the public.
1046
1047 (7) Every once in a while, "git repack" the public repository.
3eb5128a
JH
1048 Go back to step (5) and continue working.
1049
a232a132
JH
1050
1051A recommended work cycle for a "subsystem maintainer" that works
1052on that project and has own "public repository" goes like this:
3eb5128a
JH
1053
1054 (1) Prepare your work repository, by "git clone" the public
a692b965
JH
1055 repository of the "project lead". The URL used for the
1056 initial cloning is stored in .git/branches/origin.
3eb5128a
JH
1057
1058 (2) Prepare a public repository accessible to others.
1059
1060 (3) Copy over the packed files from "project lead" public
1061 repository to your public repository by hand; this part is
1062 currently not automated.
1063
1064 (4) Push into the public repository from your primary
a692b965 1065 repository. Run "git repack", and possibly "git
a232a132
JH
1066 prune-packed" if the transport used for pulling from your
1067 repository supports packed repositories.
3eb5128a 1068
a232a132
JH
1069 (5) Keep working in your primary repository. Your changes
1070 include modifications of your own, patches you receive via
1071 e-mails, and merges resulting from pulling the "public"
1072 repositories of your "project lead" and possibly your
1073 "sub-subsystem maintainers".
3eb5128a
JH
1074
1075 You can repack this private repository whenever you feel
1076 like.
1077
a232a132
JH
1078 (6) Push your changes to your public repository, and ask your
1079 "project lead" and possibly your "sub-subsystem
1080 maintainers" to pull from it.
1081
1082 (7) Every once in a while, "git repack" the public repository.
3eb5128a
JH
1083 Go back to step (5) and continue working.
1084
a232a132 1085
3eb5128a
JH
1086A recommended work cycle for an "individual developer" who does
1087not have a "public" repository is somewhat different. It goes
1088like this:
1089
a692b965
JH
1090 (1) Prepare your work repository, by "git clone" the public
1091 repository of the "project lead" (or a "subsystem
1092 maintainer", if you work on a subsystem). The URL used for
1093 the initial cloning is stored in .git/branches/origin.
3eb5128a 1094
a692b965 1095 (2) Do your work there. Make commits.
3eb5128a 1096
a692b965
JH
1097 (3) Run "git fetch origin" from the public repository of your
1098 upstream every once in a while. This does only the first
1099 half of "git pull" but does not merge. The head of the
1100 public repository is stored in .git/refs/heads/origin.
3eb5128a 1101
a692b965
JH
1102 (4) Use "git cherry origin" to see which ones of your patches
1103 were accepted, and/or use "git rebase origin" to port your
1104 unmerged changes forward to the updated upstream.
3eb5128a 1105
a692b965
JH
1106 (5) Use "git format-patch origin" to prepare patches for e-mail
1107 submission to your upstream and send it out. Go back to
1108 step (2) and continue.
3eb5128a
JH
1109
1110
1111[ to be continued.. cvsimports ]