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