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