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