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