Christian Couder | 497c833 | 2008-05-29 19:21:46 +0200 | [diff] [blame] | 1 | gitcore-tutorial(7) |
| 2 | =================== |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 3 | |
Christian Couder | 497c833 | 2008-05-29 19:21:46 +0200 | [diff] [blame] | 4 | NAME |
| 5 | ---- |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 6 | gitcore-tutorial - A Git core tutorial for developers |
Christian Couder | 497c833 | 2008-05-29 19:21:46 +0200 | [diff] [blame] | 7 | |
| 8 | SYNOPSIS |
| 9 | -------- |
| 10 | git * |
| 11 | |
| 12 | DESCRIPTION |
| 13 | ----------- |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 14 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 15 | This tutorial explains how to use the "core" Git commands to set up and |
| 16 | work with a Git repository. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 17 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 18 | If you just need to use Git as a revision control system you may prefer |
Thomas Ackermann | 48a8c26 | 2013-01-21 20:16:20 +0100 | [diff] [blame] | 19 | to start with "A Tutorial Introduction to Git" (linkgit:gittutorial[7]) or |
| 20 | link:user-manual.html[the Git User Manual]. |
J. Bruce Fields | a85feca | 2007-09-03 10:34:27 -0400 | [diff] [blame] | 21 | |
| 22 | However, an understanding of these low-level tools can be helpful if |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 23 | you want to understand Git's internals. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 24 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 25 | The core Git is often called "plumbing", with the prettier user |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Kristoffer Haugsbakk | 47437fd | 2016-12-09 16:51:12 +0100 | [diff] [blame] | 28 | plumbing does when the porcelain isn't flushing. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 29 | |
Ramkumar Ramachandra | 52eb517 | 2010-01-16 23:35:38 +0530 | [diff] [blame] | 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 | |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 38 | [NOTE] |
J. Bruce Fields | a85feca | 2007-09-03 10:34:27 -0400 | [diff] [blame] | 39 | Deeper technical details are often marked as Notes, which you can |
| 40 | skip on your first reading. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 41 | |
| 42 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 43 | Creating a Git repository |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 44 | ------------------------- |
| 45 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 46 | Creating a new Git repository couldn't be easier: all Git repositories start |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 50 | to import into Git. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 51 | |
| 52 | For our first example, we're going to start a totally new repository from |
Jonathan Nieder | ba020ef | 2008-07-03 00:41:41 -0500 | [diff] [blame] | 53 | scratch, with no pre-existing files, and we'll call it 'git-tutorial'. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 54 | To start up, create a subdirectory for it, change into that |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 55 | subdirectory, and initialize the Git infrastructure with 'git init': |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 56 | |
| 57 | ------------------------------------------------ |
| 58 | $ mkdir git-tutorial |
| 59 | $ cd git-tutorial |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 60 | $ git init |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 61 | ------------------------------------------------ |
| 62 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 63 | to which Git will reply |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 64 | |
| 65 | ---------------- |
Shawn O. Pearce | ef0a89a | 2006-12-15 00:44:58 -0500 | [diff] [blame] | 66 | Initialized empty Git repository in .git/ |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 67 | ---------------- |
| 68 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 69 | which is just Git's way of saying that you haven't been doing anything |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Jonathan Nieder | 2fd02c9 | 2008-07-03 00:55:07 -0500 | [diff] [blame] | 72 | inspect that with 'ls'. For your new empty project, it should show you |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 73 | three entries, among other things: |
| 74 | |
Junio C Hamano | 960c702 | 2006-02-06 12:27:33 -0800 | [diff] [blame] | 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. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Junio C Hamano | 960c702 | 2006-02-06 12:27:33 -0800 | [diff] [blame] | 98 | 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] | 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` |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 105 | branch. A number of the Git tools will assume that `.git/HEAD` is |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 106 | valid, though. |
| 107 | |
| 108 | [NOTE] |
Thomas Ackermann | d5fa1f1 | 2013-04-15 19:49:04 +0200 | [diff] [blame] | 109 | An 'object' is identified by its 160-bit SHA-1 hash, aka 'object name', |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 110 | and a reference to an object is always the 40-byte hex |
Thomas Ackermann | d5fa1f1 | 2013-04-15 19:49:04 +0200 | [diff] [blame] | 111 | representation of that SHA-1 name. The files in the `refs` |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 112 | subdirectory are expected to contain these hex references |
Jonathan Nieder | 70676e6 | 2010-08-20 05:37:51 -0500 | [diff] [blame] | 113 | (usually with a final `\n` at the end), and you should thus |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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] |
Jonathan Nieder | 6998e4d | 2008-06-30 17:01:21 -0500 | [diff] [blame] | 119 | An advanced user may want to take a look at linkgit:gitrepository-layout[5] |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 120 | after finishing this tutorial. |
| 121 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 122 | You have now created your first Git repository. Of course, since it's |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 123 | empty, that's not very useful, so let's start populating it with data. |
| 124 | |
| 125 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 126 | Populating a Git repository |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 133 | in your Git repository. We'll start off with a few bad examples, just to |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 134 | get a feel for how this works: |
| 135 | |
| 136 | ------------------------------------------------ |
| 137 | $ echo "Hello World" >hello |
| 138 | $ echo "Silly example" >example |
| 139 | ------------------------------------------------ |
| 140 | |
Junio C Hamano | 960c702 | 2006-02-06 12:27:33 -0800 | [diff] [blame] | 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: |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 149 | The first step is trivial: when you want to tell Git about any changes |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 150 | to your working tree, you use the 'git update-index' program. That |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Jeff King | 6cf378f | 2012-04-26 04:51:57 -0400 | [diff] [blame] | 154 | adding a new entry with the `--add` flag (or removing an entry with the |
| 155 | `--remove`) flag. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 156 | |
| 157 | So to populate the index with the two files you just created, you can do |
| 158 | |
| 159 | ------------------------------------------------ |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 160 | $ git update-index --add hello example |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 161 | ------------------------------------------------ |
| 162 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 163 | and you have now told Git to track those two files. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 164 | |
| 165 | In fact, as you did that, if you now look into your object directory, |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 166 | you'll notice that Git will have added two new objects to the object |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | ---------------- |
Junio C Hamano | a6080a0 | 2007-06-07 00:04:01 -0700 | [diff] [blame] | 177 | .git/objects/55/7db03de997c86a4a028e1ebd3a1ceb225be238 |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 178 | .git/objects/f2/4c74a2e500f5ee1332c86b94199f52b1d1d962 |
| 179 | ---------------- |
| 180 | |
Junio C Hamano | 960c702 | 2006-02-06 12:27:33 -0800 | [diff] [blame] | 181 | which correspond with the objects with names of `557db...` and |
| 182 | `f24c7...` respectively. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 183 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 184 | If you want to, you can use 'git cat-file' to look at those objects, but |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 185 | you'll have to use the object name, not the filename of the object: |
| 186 | |
| 187 | ---------------- |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 188 | $ git cat-file -t 557db03de997c86a4a028e1ebd3a1ceb225be238 |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 189 | ---------------- |
| 190 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 191 | where the `-t` tells 'git cat-file' to tell you what the "type" of the |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 192 | 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] | 193 | regular file), and you can see the contents with |
| 194 | |
| 195 | ---------------- |
Stephen Boyd | 7c5858a | 2009-11-04 22:33:53 -0800 | [diff] [blame] | 196 | $ git cat-file blob 557db03 |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 197 | ---------------- |
| 198 | |
Junio C Hamano | 960c702 | 2006-02-06 12:27:33 -0800 | [diff] [blame] | 199 | which will print out "Hello World". The object `557db03` is nothing |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 216 | was just to show that 'git update-index' did something magical, and |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 217 | actually saved away the contents of your files into the Git object |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 224 | you have not actually really "checked in" your files into Git so far, |
| 225 | you've only *told* Git about them. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 226 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 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. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 229 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 230 | In particular, let's not even check in the two files into Git yet, we'll |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 231 | start off by adding another line to `hello` first: |
| 232 | |
| 233 | ------------------------------------------------ |
| 234 | $ echo "It's a new day for git" >>hello |
| 235 | ------------------------------------------------ |
| 236 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 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 |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 239 | 'git diff-files' command: |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 240 | |
| 241 | ------------ |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 242 | $ git diff-files |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 243 | ------------ |
| 244 | |
| 245 | Oops. That wasn't very readable. It just spit out its own internal |
Jonathan Nieder | 5833d73 | 2008-07-03 00:59:09 -0500 | [diff] [blame] | 246 | version of a 'diff', but that internal version really just tells you |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 250 | To make it readable, we can tell 'git diff-files' to output the |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 251 | differences as a patch, using the `-p` flag: |
| 252 | |
| 253 | ------------ |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 254 | $ git diff-files -p |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Jean-Noel Avila | 975e382 | 2015-05-12 19:23:20 +0200 | [diff] [blame] | 262 | ------------ |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 263 | |
| 264 | i.e. the diff of the change we caused by adding another line to `hello`. |
| 265 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 266 | In other words, 'git diff-files' always shows us the difference between |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 267 | what is recorded in the index, and what is currently in the working |
| 268 | tree. That's very useful. |
| 269 | |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 270 | A common shorthand for `git diff-files -p` is to just write `git |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 285 | Committing Git state |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 286 | -------------------- |
| 287 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 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 |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 294 | Creating a tree object is trivial, and is done with 'git write-tree'. |
Jonathan Nieder | 483bc4f | 2008-06-30 13:56:34 -0500 | [diff] [blame] | 295 | There are no options or other input: `git write-tree` will take the |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 299 | creating the equivalent of a Git "directory" object: |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 300 | |
| 301 | ------------------------------------------------ |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 302 | $ git write-tree |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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, |
Jonathan Nieder | 70676e6 | 2010-08-20 05:37:51 -0500 | [diff] [blame] | 313 | you can use `git cat-file -t 8988d...` to see that this time the object |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 314 | is not a "blob" object, but a "tree" object (you can also use |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 315 | `git cat-file` to actually output the raw object contents, but you'll see |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 316 | mainly a binary mess, so that's less interesting). |
| 317 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 318 | However -- normally you'd never use 'git write-tree' on its own, because |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 319 | normally you always commit a tree into a commit object using the |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 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'. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 323 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 324 | 'git commit-tree' normally takes several arguments -- it wants to know |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 327 | the object name of the tree. However, 'git commit-tree' also wants to get a |
Luiz Fernando N. Capitulino | 79dbbed | 2007-04-25 11:18:28 -0300 | [diff] [blame] | 328 | commit message on its standard input, and it will write out the resulting |
| 329 | object name for the commit to its standard output. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 334 | that's exactly what 'git commit-tree' spits out, we can do this |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 335 | all with a sequence of simple shell commands: |
| 336 | |
| 337 | ------------------------------------------------ |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 338 | $ tree=$(git write-tree) |
| 339 | $ commit=$(echo 'Initial commit' | git commit-tree $tree) |
| 340 | $ git update-ref HEAD $commit |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 341 | ------------------------------------------------ |
| 342 | |
Nicolas Pitre | ebd124c | 2006-12-14 23:15:44 -0500 | [diff] [blame] | 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. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 356 | Remember how we did the 'git update-index' on file `hello` and then we |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 357 | changed `hello` afterward, and could compare the new state of `hello` with the |
Junio C Hamano | a6080a0 | 2007-06-07 00:04:01 -0700 | [diff] [blame] | 358 | state we saved in the index file? |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 359 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 360 | Further, remember how I said that 'git write-tree' writes the contents |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 367 | As before, if we do `git diff-files -p` in our git-tutorial project, |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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: |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 371 | 'git diff-index'. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 372 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 373 | Unlike 'git diff-files', which showed the difference between the index |
| 374 | file and the working tree, 'git diff-index' shows the differences |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 375 | between a committed *tree* and either the index file or the working |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 376 | tree. In other words, 'git diff-index' wants a tree to be diffed |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 377 | against, and before we did the commit, we couldn't do that, because we |
Junio C Hamano | a6080a0 | 2007-06-07 00:04:01 -0700 | [diff] [blame] | 378 | didn't have anything to diff against. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 379 | |
| 380 | But now we can do |
| 381 | |
| 382 | ---------------- |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 383 | $ git diff-index -p HEAD |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 384 | ---------------- |
| 385 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 386 | (where `-p` has the same meaning as it did in 'git diff-files'), and it |
Junio C Hamano | a6080a0 | 2007-06-07 00:04:01 -0700 | [diff] [blame] | 387 | will show us the same difference, but for a totally different reason. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 401 | In other words, 'git diff-index' normally compares a tree against the |
Jeff King | 6cf378f | 2012-04-26 04:51:57 -0400 | [diff] [blame] | 402 | working tree, but when given the `--cached` flag, it is told to |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 403 | instead compare against just the index cache contents, and ignore the |
| 404 | current working tree state entirely. Since we just wrote the index |
Jeff King | 6cf378f | 2012-04-26 04:51:57 -0400 | [diff] [blame] | 405 | file to HEAD, doing `git diff-index --cached -p HEAD` should thus return |
Junio C Hamano | a6080a0 | 2007-06-07 00:04:01 -0700 | [diff] [blame] | 406 | an empty set of differences, and that's exactly what it does. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 407 | |
| 408 | [NOTE] |
| 409 | ================ |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 410 | 'git diff-index' really always uses the index for its |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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, |
Jeff King | 6cf378f | 2012-04-26 04:51:57 -0400 | [diff] [blame] | 414 | regardless of whether the `--cached` flag is used or not. The `--cached` |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 415 | flag really only determines whether the file *contents* to be compared |
| 416 | come from the working tree or not. |
| 417 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 418 | This is not hard to understand, as soon as you realize that Git simply |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 419 | never knows (or cares) about files that it is not told about |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 420 | explicitly. Git will never go *looking* for files to compare, it |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | ------------------------------------------------ |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 433 | $ git update-index hello |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 434 | ------------------------------------------------ |
| 435 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 436 | (note how we didn't need the `--add` flag this time, since Git knew |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 437 | about the file already). |
| 438 | |
Jonathan Nieder | 70676e6 | 2010-08-20 05:37:51 -0500 | [diff] [blame] | 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 |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 441 | differences, but `git diff-index -p HEAD` still *does* show that the |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 442 | current state is different from the state we committed. In fact, now |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 443 | 'git diff-index' shows the same difference whether we use the `--cached` |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 467 | You've now made your first real Git commit. And if you're interested in |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 471 | commit itself ('git commit'). |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 479 | 'diff' family, namely 'git diff-tree'. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 480 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 481 | 'git diff-tree' can be given two arbitrary trees, and it will tell you the |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | ---------------- |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 488 | $ git diff-tree -p HEAD |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Jonathan Nieder | 70676e6 | 2010-08-20 05:37:51 -0500 | [diff] [blame] | 497 | various 'diff-{asterisk}' commands compare things. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 529 | More interestingly, you can also give 'git diff-tree' the `--pretty` flag, |
Junio C Hamano | 960c702 | 2006-02-06 12:27:33 -0800 | [diff] [blame] | 530 | 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] | 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 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 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 |
Junio C Hamano | 627a8b8 | 2013-08-09 10:28:53 -0700 | [diff] [blame] | 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. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 540 | |
| 541 | |
| 542 | Tagging a version |
| 543 | ----------------- |
| 544 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 545 | In Git, there are two kinds of tags, a "light" one, and an "annotated tag". |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | |
Thomas Zander | 5221ecb | 2008-01-16 23:48:21 +0100 | [diff] [blame] | 563 | to diff your current state against that tag which at this point will |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 568 | An "annotated tag" is actually a real Git object, and contains not only a |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 573 | `-s` flag to 'git tag': |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 574 | |
| 575 | ---------------- |
| 576 | $ git tag -s <tagname> |
| 577 | ---------------- |
| 578 | |
| 579 | which will sign the current `HEAD` (but you can also give it another |
Michael J Gruber | 3c652d1 | 2009-12-01 10:19:05 +0100 | [diff] [blame] | 580 | argument that specifies the thing to tag, e.g., you could have tagged the |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 593 | Git repositories are normally totally self-sufficient and relocatable. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 594 | Unlike CVS, for example, there is no separate notion of |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 595 | "repository" and "working tree". A Git repository normally *is* the |
| 596 | working tree, with the local Git information hidden in the `.git` |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 597 | subdirectory. There is nothing else. What you see is what you got. |
| 598 | |
| 599 | [NOTE] |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 600 | You can tell Git to split the Git internal information from |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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. |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 603 | So the mental model of "the Git information is always tied directly to |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | |
Junio C Hamano | a6080a0 | 2007-06-07 00:04:01 -0700 | [diff] [blame] | 607 | This has two implications: |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 619 | - if you want to move or duplicate a Git repository, you can do so. There |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 620 | is 'git clone' command, but if all you want to do is just to |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | + |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 625 | Note that when you've moved or copied a Git repository, your Git index |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | ---------------- |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 631 | $ git update-index --refresh |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 632 | ---------------- |
| 633 | + |
Martin Ågren | 7560f54 | 2017-08-23 19:49:35 +0200 | [diff] [blame] | 634 | in the new repository to make sure that the index file is up to date. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 635 | |
| 636 | Note that the second point is true even across machines. You can |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 637 | duplicate a remote Git repository with *any* regular copy mechanism, be it |
Jonathan Nieder | 2fd02c9 | 2008-07-03 00:55:07 -0500 | [diff] [blame] | 638 | 'scp', 'rsync' or 'wget'. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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), |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 644 | so usually you'll precede the 'git update-index' with a |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 645 | |
| 646 | ---------------- |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 647 | $ git read-tree --reset HEAD |
| 648 | $ git update-index --refresh |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 649 | ---------------- |
| 650 | |
| 651 | which will force a total index re-build from the tree pointed to by `HEAD`. |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 652 | It resets the index contents to `HEAD`, and then the 'git update-index' |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 653 | makes sure to match up all index entries with the checked-out files. |
| 654 | If the original repository had uncommitted changes in its |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 655 | working tree, `git update-index --refresh` notices them and |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 664 | and in fact a lot of the common Git command combinations can be scripted |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 665 | with the `git xyz` interfaces. You can learn things by just looking |
Benoit Sigoure | 3b27428 | 2007-10-29 08:00:32 +0100 | [diff] [blame] | 666 | at what the various git scripts do. For example, `git reset` used to be |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 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 |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 669 | the basic Git commands. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 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 |
Junio C Hamano | a6080a0 | 2007-06-07 00:04:01 -0700 | [diff] [blame] | 675 | repository. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 676 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 677 | To create your own local live copy of such a "raw" Git repository, you'd |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 678 | first create your own subdirectory for the project, and then copy the |
| 679 | raw repository contents into the `.git` directory. For example, to |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 680 | create your own copy of the Git repository, you'd do the following |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | |
Junio C Hamano | a6080a0 | 2007-06-07 00:04:01 -0700 | [diff] [blame] | 688 | followed by |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 689 | |
| 690 | ---------------- |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 691 | $ git read-tree HEAD |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 692 | ---------------- |
| 693 | |
| 694 | to populate the index. However, now you have populated the index, and |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 695 | you have all the Git internal files, but you will notice that you don't |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 696 | actually have any of the working tree files to work on. To get |
| 697 | those, you'd check them out with |
| 698 | |
| 699 | ---------------- |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 700 | $ git checkout-index -u -a |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 701 | ---------------- |
| 702 | |
| 703 | where the `-u` flag means that you want the checkout to keep the index |
Martin Ågren | 7560f54 | 2017-08-23 19:49:35 +0200 | [diff] [blame] | 704 | up to date (so that you don't have to refresh it afterward), and the |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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` |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 707 | flag first, to tell 'git checkout-index' to *force* overwriting of any old |
Junio C Hamano | a6080a0 | 2007-06-07 00:04:01 -0700 | [diff] [blame] | 708 | files). |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 709 | |
| 710 | Again, this can all be simplified with |
| 711 | |
| 712 | ---------------- |
Jeff King | 0d0bac6 | 2016-01-30 02:21:26 -0500 | [diff] [blame] | 713 | $ git clone git://git.kernel.org/pub/scm/git/git.git/ my-git |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Junio C Hamano | a6080a0 | 2007-06-07 00:04:01 -0700 | [diff] [blame] | 721 | repository, and checked it out. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 722 | |
| 723 | |
| 724 | Creating a new branch |
| 725 | --------------------- |
| 726 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 727 | Branches in Git are really nothing more than pointers into the Git |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Junio C Hamano | a6080a0 | 2007-06-07 00:04:01 -0700 | [diff] [blame] | 730 | these object pointers. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 731 | |
| 732 | You can at any time create a new branch by just picking an arbitrary |
Thomas Ackermann | d5fa1f1 | 2013-04-15 19:49:04 +0200 | [diff] [blame] | 733 | point in the project history, and just writing the SHA-1 name of that |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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, |
Junio C Hamano | a6080a0 | 2007-06-07 00:04:01 -0700 | [diff] [blame] | 737 | and nothing enforces it. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | ------------ |
Nguyễn Thái Ngọc Duy | 328c6cb | 2019-03-29 17:39:19 +0700 | [diff] [blame] | 744 | $ git switch -c mybranch |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 745 | ------------ |
| 746 | |
| 747 | will create a new branch based at the current `HEAD` position, and switch |
Junio C Hamano | a6080a0 | 2007-06-07 00:04:01 -0700 | [diff] [blame] | 748 | to it. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Heba Waly | 1a7e454 | 2020-01-08 00:31:36 +0000 | [diff] [blame] | 754 | just telling 'git switch' what the base of the checkout would be. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 755 | In other words, if you have an earlier tag or branch, you'd just do |
| 756 | |
| 757 | ------------ |
Nguyễn Thái Ngọc Duy | 328c6cb | 2019-03-29 17:39:19 +0700 | [diff] [blame] | 758 | $ git switch -c mybranch earlier-commit |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | ------------ |
Nguyễn Thái Ngọc Duy | 328c6cb | 2019-03-29 17:39:19 +0700 | [diff] [blame] | 768 | $ git switch master |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | |
| 774 | ------------ |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 775 | $ cat .git/HEAD |
| 776 | ------------ |
| 777 | |
Junio C Hamano | 960c702 | 2006-02-06 12:27:33 -0800 | [diff] [blame] | 778 | will tell you where it's pointing. To get the list of branches |
| 779 | you have, you can say |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 780 | |
| 781 | ------------ |
| 782 | $ git branch |
| 783 | ------------ |
| 784 | |
Benoit Sigoure | 3b27428 | 2007-10-29 08:00:32 +0100 | [diff] [blame] | 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. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | |
Junio C Hamano | a6080a0 | 2007-06-07 00:04:01 -0700 | [diff] [blame] | 795 | which will simply _create_ the branch, but will not do anything further. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 796 | You can then later -- once you decide that you want to actually develop |
Nguyễn Thái Ngọc Duy | 328c6cb | 2019-03-29 17:39:19 +0700 | [diff] [blame] | 797 | on that branch -- switch to that branch with a regular 'git switch' |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | ------------------------------------------------ |
Nguyễn Thái Ngọc Duy | 328c6cb | 2019-03-29 17:39:19 +0700 | [diff] [blame] | 811 | $ git switch mybranch |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 812 | $ echo "Work, work, work" >>hello |
Sergei Organov | d336fc0 | 2007-11-02 20:12:57 +0300 | [diff] [blame] | 813 | $ git commit -m "Some work." -i hello |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 814 | ------------------------------------------------ |
| 815 | |
| 816 | Here, we just added another line to `hello`, and we used a shorthand for |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 817 | 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] | 818 | filename directly to `git commit`, with an `-i` flag (it tells |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 819 | Git to 'include' that file in addition to what you have done to |
Junio C Hamano | 960c702 | 2006-02-06 12:27:33 -0800 | [diff] [blame] | 820 | 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] | 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 | ------------ |
Nguyễn Thái Ngọc Duy | 328c6cb | 2019-03-29 17:39:19 +0700 | [diff] [blame] | 828 | $ git switch master |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Sergei Organov | d336fc0 | 2007-11-02 20:12:57 +0300 | [diff] [blame] | 838 | $ git commit -m "Some fun." -i hello example |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | |
Jeff King | 6cf378f | 2012-04-26 04:51:57 -0400 | [diff] [blame] | 851 | will show you graphically both of your branches (that's what the `--all` |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Junio C Hamano | a6080a0 | 2007-06-07 00:04:01 -0700 | [diff] [blame] | 854 | source. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 855 | |
Jonathan Nieder | 42d36bb | 2008-07-03 00:49:55 -0500 | [diff] [blame] | 856 | Anyway, let's exit 'gitk' (`^Q` or the File menu), and decide that we want |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 859 | script called 'git merge', which wants to know which branches you want |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 860 | to resolve and what the merge is all about: |
| 861 | |
| 862 | ------------ |
Sergei Organov | ba17892 | 2007-10-30 22:54:02 +0300 | [diff] [blame] | 863 | $ git merge -m "Merge work in mybranch" mybranch |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 870 | merge will need to be fixed up by hand, though, so Git will do as much |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | ---------------- |
Junio C Hamano | a6080a0 | 2007-06-07 00:04:01 -0700 | [diff] [blame] | 875 | Auto-merging hello |
| 876 | CONFLICT (content): Merge conflict in hello |
Markus Heidelberg | ec9f0ea | 2008-12-19 13:14:52 +0100 | [diff] [blame] | 877 | Automatic merge failed; fix conflicts and then commit the result. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 878 | ---------------- |
| 879 | |
Junio C Hamano | 5fe3acc | 2007-01-14 21:31:30 -0800 | [diff] [blame] | 880 | It tells you that it did an "Automatic merge", which |
| 881 | failed due to conflicts in `hello`. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | ------------ |
Junio C Hamano | 130fcca | 2006-02-05 00:07:44 -0800 | [diff] [blame] | 898 | $ git commit -i hello |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 903 | message about your adventures in 'git merge'-land. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 904 | |
Jeff King | 6cf378f | 2012-04-26 04:51:57 -0400 | [diff] [blame] | 905 | After you're done, start up `gitk --all` to see graphically what the |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 909 | from the `master` branch, Git will know how you merged it, so you'll not |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | ------------------------------------------------ |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 916 | $ git show-branch --topo-order --more=1 master mybranch |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 917 | * [master] Merge work in mybranch |
| 918 | ! [mybranch] Some work. |
| 919 | -- |
| 920 | - [master] Merge work in mybranch |
| 921 | *+ [mybranch] Some work. |
Sergei Organov | 2782c93 | 2007-11-08 18:10:28 +0300 | [diff] [blame] | 922 | * [master^] Some fun. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 923 | ------------------------------------------------ |
| 924 | |
| 925 | The first two lines indicate that it is showing the two branches |
Jeremy White | 52ffe99 | 2012-09-13 17:27:09 -0500 | [diff] [blame] | 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 |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 929 | `master` branch, and the second column for the `mybranch` |
Jeremy White | 52ffe99 | 2012-09-13 17:27:09 -0500 | [diff] [blame] | 930 | branch. Three commits are shown along with their titles. |
Jeff King | 6cf378f | 2012-04-26 04:51:57 -0400 | [diff] [blame] | 931 | All of them have non blank characters in the first column (`*` |
Benoit Sigoure | 3b27428 | 2007-10-29 08:00:32 +0100 | [diff] [blame] | 932 | shows an ordinary commit on the current branch, `-` is a merge commit), which |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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' |
Sergei Organov | 2782c93 | 2007-11-08 18:10:28 +0300 | [diff] [blame] | 939 | are branch heads. 'master^' is the first parent of 'master' |
Jonathan Nieder | 9d83e38 | 2010-10-11 11:03:32 -0500 | [diff] [blame] | 940 | branch head. Please see linkgit:gitrevisions[7] if you want to |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 941 | see more complex cases. |
| 942 | |
Sergei Organov | 2782c93 | 2007-11-08 18:10:28 +0300 | [diff] [blame] | 943 | [NOTE] |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 944 | Without the '--more=1' option, 'git show-branch' would not output the |
Sergei Organov | 2782c93 | 2007-11-08 18:10:28 +0300 | [diff] [blame] | 945 | '[master^]' commit, as '[mybranch]' commit is a common ancestor of |
Jonathan Nieder | 483bc4f | 2008-06-30 13:56:34 -0500 | [diff] [blame] | 946 | both 'master' and 'mybranch' tips. Please see linkgit:git-show-branch[1] |
| 947 | for details. |
Sergei Organov | 2782c93 | 2007-11-08 18:10:28 +0300 | [diff] [blame] | 948 | |
| 949 | [NOTE] |
| 950 | If there were more commits on the 'master' branch after the merge, the |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 951 | merge commit itself would not be shown by 'git show-branch' by |
Matthieu Moy | bcf9626 | 2016-06-28 13:40:11 +0200 | [diff] [blame] | 952 | default. You would need to provide `--sparse` option to make the |
Sergei Organov | 2782c93 | 2007-11-08 18:10:28 +0300 | [diff] [blame] | 953 | merge commit visible in this case. |
| 954 | |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 958 | 'git merge' to get the "upstream changes" back to your branch. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 959 | |
| 960 | ------------ |
Nguyễn Thái Ngọc Duy | 328c6cb | 2019-03-29 17:39:19 +0700 | [diff] [blame] | 961 | $ git switch mybranch |
Sergei Organov | ba17892 | 2007-10-30 22:54:02 +0300 | [diff] [blame] | 962 | $ git merge -m "Merge upstream changes." master |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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.... |
Felipe Contreras | a75d7b5 | 2009-10-24 11:31:32 +0300 | [diff] [blame] | 970 | Fast-forward (no commit created; -m option ignored) |
Zbigniew Jędrzejewski-Szmek | dc801e7 | 2012-04-30 22:38:58 +0200 | [diff] [blame] | 971 | example | 1 + |
| 972 | hello | 1 + |
Nguyễn Thái Ngọc Duy | 7f81463 | 2012-02-01 19:55:07 +0700 | [diff] [blame] | 973 | 2 files changed, 2 insertions(+) |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 974 | ---------------- |
| 975 | |
Markus Heidelberg | 04c8ce9 | 2008-12-19 13:14:18 +0100 | [diff] [blame] | 976 | Because your branch did not contain anything more than what had |
| 977 | already been merged into the `master` branch, the merge operation did |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Felipe Contreras | a75d7b5 | 2009-10-24 11:31:32 +0300 | [diff] [blame] | 980 | often called 'fast-forward' merge. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 981 | |
Jeff King | 6cf378f | 2012-04-26 04:51:57 -0400 | [diff] [blame] | 982 | You can run `gitk --all` again to see how the commit ancestry |
Jonathan Nieder | 5833d73 | 2008-07-03 00:59:09 -0500 | [diff] [blame] | 983 | looks like, or run 'show-branch', which tells you this. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 998 | merging with your own branches, so it's worth pointing out that Git |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 999 | makes that very easy too, and in fact, it's not that different from |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 1000 | doing a 'git merge'. In fact, a remote merge ends up being nothing |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1001 | more than "fetch the work from a remote repository into a temporary tag" |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 1002 | followed by a 'git merge'. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1003 | |
| 1004 | Fetching from a remote repository is done by, unsurprisingly, |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 1005 | 'git fetch': |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1024 | most efficient way to exchange Git objects between repositories. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1025 | |
| 1026 | Local directory:: |
| 1027 | `/path/to/repo.git/` |
| 1028 | + |
Jonathan Nieder | 2fd02c9 | 2008-07-03 00:55:07 -0500 | [diff] [blame] | 1029 | This transport is the same as SSH transport but uses 'sh' to run |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1030 | both ends on the local machine instead of running other end on |
Jonathan Nieder | 2fd02c9 | 2008-07-03 00:55:07 -0500 | [diff] [blame] | 1031 | the remote machine via 'ssh'. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1032 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1033 | Git Native:: |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Jonathan Nieder | 70676e6 | 2010-08-20 05:37:51 -0500 | [diff] [blame] | 1047 | commit object by downloading from `repo.git/objects/xx/xxx...` |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Horst H. von Brand | abda1ef | 2006-06-03 16:27:26 -0400 | [diff] [blame] | 1051 | necessary objects. Because of this behavior, they are |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1052 | sometimes also called 'commit walkers'. |
| 1053 | + |
| 1054 | The 'commit walkers' are sometimes also called 'dumb |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1055 | transports', because they do not require any Git aware smart |
| 1056 | server like Git Native transport does. Any stock HTTP server |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1057 | that does not even support directory index would suffice. But |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 1058 | you must prepare your repository with 'git update-server-info' |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1059 | to help dumb transport downloaders. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1060 | |
Junio C Hamano | 207dfa0 | 2007-02-07 10:37:03 -0800 | [diff] [blame] | 1061 | Once you fetch from the remote repository, you `merge` that |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1062 | with your current branch. |
| 1063 | |
| 1064 | However -- it's such a common thing to `fetch` and then |
Junio C Hamano | 207dfa0 | 2007-02-07 10:37:03 -0800 | [diff] [blame] | 1065 | immediately `merge`, that it's called `git pull`, and you can |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 1078 | branches, and merging between them with 'git pull', just like |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1079 | you merge between branches. The advantage of this approach is |
Mike Coleman | aacd404 | 2007-02-02 00:25:30 -0600 | [diff] [blame] | 1080 | that it lets you keep a set of files for each `branch` checked |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 |
Nicolas Pitre | c14261e | 2007-01-14 22:44:18 -0500 | [diff] [blame] | 1088 | the remote repository URL in the local repository's config file |
| 1089 | like this: |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1090 | |
| 1091 | ------------------------------------------------ |
Tom Prince | e0d10e1 | 2007-01-28 16:16:53 -0800 | [diff] [blame] | 1092 | $ git config remote.linus.url http://www.kernel.org/pub/scm/git/git.git/ |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1093 | ------------------------------------------------ |
| 1094 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 1095 | and use the "linus" keyword with 'git pull' instead of the full URL. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1096 | |
| 1097 | Examples. |
| 1098 | |
| 1099 | . `git pull linus` |
| 1100 | . `git pull linus tag v0.99.1` |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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` |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | ------------ |
Sergei Organov | 065c5ac | 2007-11-10 16:17:33 +0300 | [diff] [blame] | 1122 | $ git show-branch --more=2 master mybranch |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 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 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 1131 | Remember, before running 'git merge', our `master` head was at |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1132 | "Some fun." commit, while our `mybranch` head was at "Some |
| 1133 | work." commit. |
| 1134 | |
| 1135 | ------------ |
Nguyễn Thái Ngọc Duy | 328c6cb | 2019-03-29 17:39:19 +0700 | [diff] [blame] | 1136 | $ git switch -C mybranch master^2 |
| 1137 | $ git switch master |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1138 | $ git reset --hard master^ |
| 1139 | ------------ |
| 1140 | |
| 1141 | After rewinding, the commit structure should look like this: |
| 1142 | |
| 1143 | ------------ |
| 1144 | $ git show-branch |
| 1145 | * [master] Some fun. |
| 1146 | ! [mybranch] Some work. |
| 1147 | -- |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1148 | * [master] Some fun. |
Nanako Shiraishi | 5d166cc | 2009-11-25 08:08:08 +0900 | [diff] [blame] | 1149 | + [mybranch] Some work. |
| 1150 | *+ [master^] Initial commit |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1151 | ------------ |
| 1152 | |
| 1153 | Now we are ready to experiment with the merge by hand. |
| 1154 | |
| 1155 | `git merge` command, when merging two branches, uses 3-way merge |
| 1156 | algorithm. First, it finds the common ancestor between them. |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 1157 | The command it uses is 'git merge-base': |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1158 | |
| 1159 | ------------ |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 1160 | $ mb=$(git merge-base HEAD mybranch) |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1161 | ------------ |
| 1162 | |
| 1163 | The command writes the commit object name of the common ancestor |
| 1164 | to the standard output, so we captured its output to a variable, |
Benoit Sigoure | 3b27428 | 2007-10-29 08:00:32 +0100 | [diff] [blame] | 1165 | because we will be using it in the next step. By the way, the common |
Stephen Boyd | 7c5858a | 2009-11-04 22:33:53 -0800 | [diff] [blame] | 1166 | ancestor commit is the "Initial commit" commit in this case. You can |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1167 | tell it by: |
| 1168 | |
| 1169 | ------------ |
Stephen Boyd | 7c5858a | 2009-11-04 22:33:53 -0800 | [diff] [blame] | 1170 | $ git name-rev --name-only --tags $mb |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1171 | my-first-tag |
| 1172 | ------------ |
| 1173 | |
| 1174 | After finding out a common ancestor commit, the second step is |
| 1175 | this: |
| 1176 | |
| 1177 | ------------ |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 1178 | $ git read-tree -m -u $mb HEAD mybranch |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1179 | ------------ |
| 1180 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 1181 | This is the same 'git read-tree' command we have already seen, |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1182 | but it takes three trees, unlike previous examples. This reads |
| 1183 | the contents of each tree into different 'stage' in the index |
Sergei Organov | 065c5ac | 2007-11-10 16:17:33 +0300 | [diff] [blame] | 1184 | file (the first tree goes to stage 1, the second to stage 2, |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1185 | etc.). After reading three trees into three stages, the paths |
| 1186 | that are the same in all three stages are 'collapsed' into stage |
| 1187 | 0. Also paths that are the same in two of three stages are |
Thomas Ackermann | d5fa1f1 | 2013-04-15 19:49:04 +0200 | [diff] [blame] | 1188 | collapsed into stage 0, taking the SHA-1 from either stage 2 or |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1189 | stage 3, whichever is different from stage 1 (i.e. only one side |
| 1190 | changed from the common ancestor). |
| 1191 | |
| 1192 | After 'collapsing' operation, paths that are different in three |
| 1193 | trees are left in non-zero stages. At this point, you can |
| 1194 | inspect the index file with this command: |
| 1195 | |
| 1196 | ------------ |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 1197 | $ git ls-files --stage |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1198 | 100644 7f8b141b65fdcee47321e399a2598a235a032422 0 example |
Stephen Boyd | 7c5858a | 2009-11-04 22:33:53 -0800 | [diff] [blame] | 1199 | 100644 557db03de997c86a4a028e1ebd3a1ceb225be238 1 hello |
| 1200 | 100644 ba42a2a96e3027f3333e13ede4ccf4498c3ae942 2 hello |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1201 | 100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello |
| 1202 | ------------ |
| 1203 | |
| 1204 | In our example of only two files, we did not have unchanged |
Jon Loeliger | 323b9db | 2009-01-12 14:02:07 -0600 | [diff] [blame] | 1205 | files so only 'example' resulted in collapsing. But in real-life |
| 1206 | large projects, when only a small number of files change in one commit, |
| 1207 | this 'collapsing' tends to trivially merge most of the paths |
| 1208 | fairly quickly, leaving only a handful of real changes in non-zero |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1209 | stages. |
| 1210 | |
Jeff King | 6cf378f | 2012-04-26 04:51:57 -0400 | [diff] [blame] | 1211 | To look at only non-zero stages, use `--unmerged` flag: |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1212 | |
| 1213 | ------------ |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 1214 | $ git ls-files --unmerged |
Stephen Boyd | 7c5858a | 2009-11-04 22:33:53 -0800 | [diff] [blame] | 1215 | 100644 557db03de997c86a4a028e1ebd3a1ceb225be238 1 hello |
| 1216 | 100644 ba42a2a96e3027f3333e13ede4ccf4498c3ae942 2 hello |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1217 | 100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello |
| 1218 | ------------ |
| 1219 | |
| 1220 | The next step of merging is to merge these three versions of the |
| 1221 | file, using 3-way merge. This is done by giving |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 1222 | 'git merge-one-file' command as one of the arguments to |
| 1223 | 'git merge-index' command: |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1224 | |
| 1225 | ------------ |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 1226 | $ git merge-index git-merge-one-file hello |
Markus Heidelberg | ec9f0ea | 2008-12-19 13:14:52 +0100 | [diff] [blame] | 1227 | Auto-merging hello |
| 1228 | ERROR: Merge conflict in hello |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1229 | fatal: merge program failed |
| 1230 | ------------ |
| 1231 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 1232 | 'git merge-one-file' script is called with parameters to |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1233 | describe those three versions, and is responsible to leave the |
| 1234 | merge results in the working tree. |
| 1235 | It is a fairly straightforward shell script, and |
Jonathan Nieder | 2fd02c9 | 2008-07-03 00:55:07 -0500 | [diff] [blame] | 1236 | eventually calls 'merge' program from RCS suite to perform a |
| 1237 | file-level 3-way merge. In this case, 'merge' detects |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1238 | conflicts, and the merge result with conflict marks is left in |
| 1239 | the working tree.. This can be seen if you run `ls-files |
| 1240 | --stage` again at this point: |
| 1241 | |
| 1242 | ------------ |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 1243 | $ git ls-files --stage |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1244 | 100644 7f8b141b65fdcee47321e399a2598a235a032422 0 example |
Stephen Boyd | 7c5858a | 2009-11-04 22:33:53 -0800 | [diff] [blame] | 1245 | 100644 557db03de997c86a4a028e1ebd3a1ceb225be238 1 hello |
| 1246 | 100644 ba42a2a96e3027f3333e13ede4ccf4498c3ae942 2 hello |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1247 | 100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello |
| 1248 | ------------ |
| 1249 | |
| 1250 | This is the state of the index file and the working file after |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 1251 | 'git merge' returns control back to you, leaving the conflicting |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1252 | merge for you to resolve. Notice that the path `hello` is still |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 1253 | unmerged, and what you see with 'git diff' at this point is |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1254 | differences since stage 2 (i.e. your version). |
| 1255 | |
| 1256 | |
| 1257 | Publishing your work |
| 1258 | -------------------- |
| 1259 | |
Mike Coleman | aacd404 | 2007-02-02 00:25:30 -0600 | [diff] [blame] | 1260 | So, we can use somebody else's work from a remote repository, but |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1261 | how can *you* prepare a repository to let other people pull from |
| 1262 | it? |
| 1263 | |
Luiz Fernando N. Capitulino | 79dbbed | 2007-04-25 11:18:28 -0300 | [diff] [blame] | 1264 | You do your real work in your working tree that has your |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1265 | primary repository hanging under it as its `.git` subdirectory. |
| 1266 | You *could* make that repository accessible remotely and ask |
| 1267 | people to pull from it, but in practice that is not the way |
| 1268 | things are usually done. A recommended way is to have a public |
| 1269 | repository, make it reachable by other people, and when the |
| 1270 | changes you made in your primary working tree are in good shape, |
| 1271 | update the public repository from it. This is often called |
| 1272 | 'pushing'. |
| 1273 | |
| 1274 | [NOTE] |
| 1275 | This public repository could further be mirrored, and that is |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1276 | how Git repositories at `kernel.org` are managed. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1277 | |
| 1278 | Publishing the changes from your local (private) repository to |
| 1279 | your remote (public) repository requires a write privilege on |
| 1280 | the remote machine. You need to have an SSH account there to |
Jonathan Nieder | ba020ef | 2008-07-03 00:41:41 -0500 | [diff] [blame] | 1281 | run a single command, 'git-receive-pack'. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1282 | |
| 1283 | First, you need to create an empty repository on the remote |
| 1284 | machine that will house your public repository. This empty |
Martin Ågren | 7560f54 | 2017-08-23 19:49:35 +0200 | [diff] [blame] | 1285 | repository will be populated and be kept up to date by pushing |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1286 | into it later. Obviously, this repository creation needs to be |
| 1287 | done only once. |
| 1288 | |
| 1289 | [NOTE] |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 1290 | 'git push' uses a pair of commands, |
| 1291 | 'git send-pack' on your local machine, and 'git-receive-pack' |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1292 | on the remote machine. The communication between the two over |
| 1293 | the network internally uses an SSH connection. |
| 1294 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1295 | Your private repository's Git directory is usually `.git`, but |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1296 | your public repository is often named after the project name, |
| 1297 | i.e. `<project>.git`. Let's create such a public repository for |
| 1298 | project `my-git`. After logging into the remote machine, create |
| 1299 | an empty directory: |
| 1300 | |
| 1301 | ------------ |
| 1302 | $ mkdir my-git.git |
| 1303 | ------------ |
| 1304 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1305 | Then, make that directory into a Git repository by running |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 1306 | '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] | 1307 | `.git`, we do things slightly differently: |
| 1308 | |
| 1309 | ------------ |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 1310 | $ GIT_DIR=my-git.git git init |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1311 | ------------ |
| 1312 | |
| 1313 | Make sure this directory is available for others you want your |
Markus Heidelberg | 04c8ce9 | 2008-12-19 13:14:18 +0100 | [diff] [blame] | 1314 | changes to be pulled via the transport of your choice. Also |
Jonathan Nieder | ba020ef | 2008-07-03 00:41:41 -0500 | [diff] [blame] | 1315 | you need to make sure that you have the 'git-receive-pack' |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1316 | program on the `$PATH`. |
| 1317 | |
| 1318 | [NOTE] |
| 1319 | Many installations of sshd do not invoke your shell as the login |
| 1320 | shell when you directly run programs; what this means is that if |
Jonathan Nieder | 2fd02c9 | 2008-07-03 00:55:07 -0500 | [diff] [blame] | 1321 | your login shell is 'bash', only `.bashrc` is read and not |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1322 | `.bash_profile`. As a workaround, make sure `.bashrc` sets up |
Jonathan Nieder | ba020ef | 2008-07-03 00:41:41 -0500 | [diff] [blame] | 1323 | `$PATH` so that you can run 'git-receive-pack' program. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1324 | |
| 1325 | [NOTE] |
| 1326 | If you plan to publish this repository to be accessed over http, |
Petr Baudis | 7dce991 | 2008-08-12 00:34:46 +0200 | [diff] [blame] | 1327 | you should do `mv my-git.git/hooks/post-update.sample |
| 1328 | my-git.git/hooks/post-update` at this point. |
| 1329 | This makes sure that every time you push into this |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 1330 | repository, `git update-server-info` is run. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1331 | |
| 1332 | Your "public repository" is now ready to accept your changes. |
| 1333 | Come back to the machine you have your private repository. From |
| 1334 | there, run this command: |
| 1335 | |
| 1336 | ------------ |
| 1337 | $ git push <public-host>:/path/to/my-git.git master |
| 1338 | ------------ |
| 1339 | |
| 1340 | This synchronizes your public repository to match the named |
| 1341 | branch head (i.e. `master` in this case) and objects reachable |
| 1342 | from them in your current repository. |
| 1343 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1344 | As a real example, this is how I update my public Git |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1345 | repository. Kernel.org mirror network takes care of the |
| 1346 | propagation to other publicly visible machines: |
| 1347 | |
| 1348 | ------------ |
Junio C Hamano | a6080a0 | 2007-06-07 00:04:01 -0700 | [diff] [blame] | 1349 | $ git push master.kernel.org:/pub/scm/git/git.git/ |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1350 | ------------ |
| 1351 | |
| 1352 | |
| 1353 | Packing your repository |
| 1354 | ----------------------- |
| 1355 | |
| 1356 | Earlier, we saw that one file under `.git/objects/??/` directory |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1357 | is stored for each Git object you create. This representation |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1358 | is efficient to create atomically and safely, but |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1359 | not so convenient to transport over the network. Since Git objects are |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1360 | immutable once they are created, there is a way to optimize the |
| 1361 | storage by "packing them together". The command |
| 1362 | |
| 1363 | ------------ |
| 1364 | $ git repack |
| 1365 | ------------ |
| 1366 | |
| 1367 | will do it for you. If you followed the tutorial examples, you |
| 1368 | would have accumulated about 17 objects in `.git/objects/??/` |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 1369 | directories by now. 'git repack' tells you how many objects it |
Kristoffer Haugsbakk | 8b9bb33 | 2016-12-09 16:51:09 +0100 | [diff] [blame] | 1370 | packed, and stores the packed file in the `.git/objects/pack` |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1371 | directory. |
| 1372 | |
| 1373 | [NOTE] |
Jeff King | 6cf378f | 2012-04-26 04:51:57 -0400 | [diff] [blame] | 1374 | You will see two files, `pack-*.pack` and `pack-*.idx`, |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1375 | in `.git/objects/pack` directory. They are closely related to |
| 1376 | each other, and if you ever copy them by hand to a different |
| 1377 | repository for whatever reason, you should make sure you copy |
| 1378 | them together. The former holds all the data from the objects |
| 1379 | in the pack, and the latter holds the index for random |
| 1380 | access. |
| 1381 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 1382 | If you are paranoid, running 'git verify-pack' command would |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1383 | detect if you have a corrupt pack, but do not worry too much. |
| 1384 | Our programs are always perfect ;-). |
| 1385 | |
| 1386 | Once you have packed objects, you do not need to leave the |
| 1387 | unpacked objects that are contained in the pack file anymore. |
| 1388 | |
| 1389 | ------------ |
| 1390 | $ git prune-packed |
| 1391 | ------------ |
| 1392 | |
| 1393 | would remove them for you. |
| 1394 | |
| 1395 | You can try running `find .git/objects -type f` before and after |
| 1396 | you run `git prune-packed` if you are curious. Also `git |
| 1397 | count-objects` would tell you how many unpacked objects are in |
| 1398 | your repository and how much space they are consuming. |
| 1399 | |
| 1400 | [NOTE] |
| 1401 | `git pull` is slightly cumbersome for HTTP transport, as a |
| 1402 | packed repository may contain relatively few objects in a |
| 1403 | relatively large pack. If you expect many HTTP pulls from your |
| 1404 | public repository you might want to repack & prune often, or |
| 1405 | never. |
| 1406 | |
| 1407 | If you run `git repack` again at this point, it will say |
Markus Heidelberg | ec9f0ea | 2008-12-19 13:14:52 +0100 | [diff] [blame] | 1408 | "Nothing new to pack.". Once you continue your development and |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1409 | accumulate the changes, running `git repack` again will create a |
| 1410 | new pack, that contains objects created since you packed your |
| 1411 | repository the last time. We recommend that you pack your project |
| 1412 | soon after the initial import (unless you are starting your |
| 1413 | project from scratch), and then run `git repack` every once in a |
| 1414 | while, depending on how active your project is. |
| 1415 | |
| 1416 | When a repository is synchronized via `git push` and `git pull` |
| 1417 | objects packed in the source repository are usually stored |
Jeff King | 0d0bac6 | 2016-01-30 02:21:26 -0500 | [diff] [blame] | 1418 | unpacked in the destination. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1419 | While this allows you to use different packing strategies on |
| 1420 | both ends, it also means you may need to repack both |
| 1421 | repositories every once in a while. |
| 1422 | |
| 1423 | |
| 1424 | Working with Others |
| 1425 | ------------------- |
| 1426 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1427 | Although Git is a truly distributed system, it is often |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1428 | convenient to organize your project with an informal hierarchy |
| 1429 | of developers. Linux kernel development is run this way. There |
Junio C Hamano | 505739f | 2007-02-02 23:17:34 -0800 | [diff] [blame] | 1430 | is a nice illustration (page 17, "Merges to Mainline") in |
Jeff King | f991c62 | 2017-04-20 16:33:49 -0400 | [diff] [blame] | 1431 | https://web.archive.org/web/20120915203609/http://www.xenotime.net/linux/mentor/linux-mentoring-2006.pdf[Randy Dunlap's presentation]. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1432 | |
| 1433 | It should be stressed that this hierarchy is purely *informal*. |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1434 | There is nothing fundamental in Git that enforces the "chain of |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1435 | patch flow" this hierarchy implies. You do not have to pull |
| 1436 | from only one remote repository. |
| 1437 | |
| 1438 | A recommended workflow for a "project lead" goes like this: |
| 1439 | |
| 1440 | 1. Prepare your primary repository on your local machine. Your |
| 1441 | work is done there. |
| 1442 | |
| 1443 | 2. Prepare a public repository accessible to others. |
| 1444 | + |
| 1445 | If other people are pulling from your repository over dumb |
| 1446 | transport protocols (HTTP), you need to keep this repository |
Nicolas Pitre | 5c94f87 | 2007-01-12 16:01:46 -0500 | [diff] [blame] | 1447 | 'dumb transport friendly'. After `git init`, |
Petr Baudis | 7dce991 | 2008-08-12 00:34:46 +0200 | [diff] [blame] | 1448 | `$GIT_DIR/hooks/post-update.sample` copied from the standard templates |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 1449 | would contain a call to 'git update-server-info' |
Petr Baudis | 7dce991 | 2008-08-12 00:34:46 +0200 | [diff] [blame] | 1450 | but you need to manually enable the hook with |
| 1451 | `mv post-update.sample post-update`. This makes sure |
Martin Ågren | 7560f54 | 2017-08-23 19:49:35 +0200 | [diff] [blame] | 1452 | 'git update-server-info' keeps the necessary files up to date. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1453 | |
| 1454 | 3. Push into the public repository from your primary |
| 1455 | repository. |
| 1456 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 1457 | 4. 'git repack' the public repository. This establishes a big |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1458 | pack that contains the initial set of objects as the |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 1459 | baseline, and possibly 'git prune' if the transport |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1460 | used for pulling from your repository supports packed |
| 1461 | repositories. |
| 1462 | |
| 1463 | 5. Keep working in your primary repository. Your changes |
| 1464 | include modifications of your own, patches you receive via |
| 1465 | e-mails, and merges resulting from pulling the "public" |
| 1466 | repositories of your "subsystem maintainers". |
| 1467 | + |
| 1468 | You can repack this private repository whenever you feel like. |
| 1469 | |
| 1470 | 6. Push your changes to the public repository, and announce it |
| 1471 | to the public. |
| 1472 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 1473 | 7. Every once in a while, 'git repack' the public repository. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1474 | Go back to step 5. and continue working. |
| 1475 | |
| 1476 | |
| 1477 | A recommended work cycle for a "subsystem maintainer" who works |
| 1478 | on that project and has an own "public repository" goes like this: |
| 1479 | |
Kristoffer Haugsbakk | f383e4e | 2016-12-09 16:51:10 +0100 | [diff] [blame] | 1480 | 1. Prepare your work repository, by running 'git clone' on the public |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1481 | repository of the "project lead". The URL used for the |
Nicolas Pitre | c14261e | 2007-01-14 22:44:18 -0500 | [diff] [blame] | 1482 | initial cloning is stored in the remote.origin.url |
| 1483 | configuration variable. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1484 | |
| 1485 | 2. Prepare a public repository accessible to others, just like |
| 1486 | the "project lead" person does. |
| 1487 | |
| 1488 | 3. Copy over the packed files from "project lead" public |
| 1489 | repository to your public repository, unless the "project |
| 1490 | lead" repository lives on the same machine as yours. In the |
| 1491 | latter case, you can use `objects/info/alternates` file to |
| 1492 | point at the repository you are borrowing from. |
| 1493 | |
| 1494 | 4. Push into the public repository from your primary |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 1495 | repository. Run 'git repack', and possibly 'git prune' if the |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1496 | transport used for pulling from your repository supports |
| 1497 | packed repositories. |
| 1498 | |
| 1499 | 5. Keep working in your primary repository. Your changes |
| 1500 | include modifications of your own, patches you receive via |
| 1501 | e-mails, and merges resulting from pulling the "public" |
| 1502 | repositories of your "project lead" and possibly your |
| 1503 | "sub-subsystem maintainers". |
| 1504 | + |
| 1505 | You can repack this private repository whenever you feel |
| 1506 | like. |
| 1507 | |
| 1508 | 6. Push your changes to your public repository, and ask your |
| 1509 | "project lead" and possibly your "sub-subsystem |
| 1510 | maintainers" to pull from it. |
| 1511 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 1512 | 7. Every once in a while, 'git repack' the public repository. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1513 | Go back to step 5. and continue working. |
| 1514 | |
| 1515 | |
| 1516 | A recommended work cycle for an "individual developer" who does |
| 1517 | not have a "public" repository is somewhat different. It goes |
| 1518 | like this: |
| 1519 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 1520 | 1. Prepare your work repository, by 'git clone' the public |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1521 | repository of the "project lead" (or a "subsystem |
| 1522 | maintainer", if you work on a subsystem). The URL used for |
Nicolas Pitre | c14261e | 2007-01-14 22:44:18 -0500 | [diff] [blame] | 1523 | the initial cloning is stored in the remote.origin.url |
| 1524 | configuration variable. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1525 | |
| 1526 | 2. Do your work in your repository on 'master' branch. |
| 1527 | |
| 1528 | 3. Run `git fetch origin` from the public repository of your |
| 1529 | upstream every once in a while. This does only the first |
| 1530 | half of `git pull` but does not merge. The head of the |
Nicolas Pitre | c14261e | 2007-01-14 22:44:18 -0500 | [diff] [blame] | 1531 | public repository is stored in `.git/refs/remotes/origin/master`. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1532 | |
| 1533 | 4. Use `git cherry origin` to see which ones of your patches |
| 1534 | were accepted, and/or use `git rebase origin` to port your |
| 1535 | unmerged changes forward to the updated upstream. |
| 1536 | |
| 1537 | 5. Use `git format-patch origin` to prepare patches for e-mail |
| 1538 | submission to your upstream and send it out. Go back to |
| 1539 | step 2. and continue. |
| 1540 | |
| 1541 | |
| 1542 | Working with Others, Shared Repository Style |
| 1543 | -------------------------------------------- |
| 1544 | |
Kristoffer Haugsbakk | 8b9bb33 | 2016-12-09 16:51:09 +0100 | [diff] [blame] | 1545 | If you are coming from a CVS background, the style of cooperation |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1546 | suggested in the previous section may be new to you. You do not |
Kristoffer Haugsbakk | 8b9bb33 | 2016-12-09 16:51:09 +0100 | [diff] [blame] | 1547 | have to worry. Git supports the "shared public repository" style of |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1548 | cooperation you are probably more familiar with as well. |
| 1549 | |
Jonathan Nieder | 6998e4d | 2008-06-30 17:01:21 -0500 | [diff] [blame] | 1550 | See linkgit:gitcvs-migration[7] for the details. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1551 | |
| 1552 | Bundling your work together |
| 1553 | --------------------------- |
| 1554 | |
| 1555 | It is likely that you will be working on more than one thing at |
| 1556 | a time. It is easy to manage those more-or-less independent tasks |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1557 | using branches with Git. |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1558 | |
| 1559 | We have already seen how branches work previously, |
| 1560 | with "fun and work" example using two branches. The idea is the |
| 1561 | same if there are more than two branches. Let's say you started |
| 1562 | out from "master" head, and have some new code in the "master" |
| 1563 | branch, and two independent fixes in the "commit-fix" and |
| 1564 | "diff-fix" branches: |
| 1565 | |
| 1566 | ------------ |
| 1567 | $ git show-branch |
| 1568 | ! [commit-fix] Fix commit message normalization. |
| 1569 | ! [diff-fix] Fix rename detection. |
| 1570 | * [master] Release candidate #1 |
| 1571 | --- |
| 1572 | + [diff-fix] Fix rename detection. |
| 1573 | + [diff-fix~1] Better common substring algorithm. |
| 1574 | + [commit-fix] Fix commit message normalization. |
| 1575 | * [master] Release candidate #1 |
| 1576 | ++* [diff-fix~2] Pretty-print messages. |
| 1577 | ------------ |
| 1578 | |
| 1579 | Both fixes are tested well, and at this point, you want to merge |
| 1580 | in both of them. You could merge in 'diff-fix' first and then |
| 1581 | 'commit-fix' next, like this: |
| 1582 | |
| 1583 | ------------ |
Sergei Organov | d336fc0 | 2007-11-02 20:12:57 +0300 | [diff] [blame] | 1584 | $ git merge -m "Merge fix in diff-fix" diff-fix |
| 1585 | $ git merge -m "Merge fix in commit-fix" commit-fix |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1586 | ------------ |
| 1587 | |
| 1588 | Which would result in: |
| 1589 | |
| 1590 | ------------ |
| 1591 | $ git show-branch |
| 1592 | ! [commit-fix] Fix commit message normalization. |
| 1593 | ! [diff-fix] Fix rename detection. |
| 1594 | * [master] Merge fix in commit-fix |
| 1595 | --- |
| 1596 | - [master] Merge fix in commit-fix |
| 1597 | + * [commit-fix] Fix commit message normalization. |
| 1598 | - [master~1] Merge fix in diff-fix |
| 1599 | +* [diff-fix] Fix rename detection. |
| 1600 | +* [diff-fix~1] Better common substring algorithm. |
| 1601 | * [master~2] Release candidate #1 |
| 1602 | ++* [master~3] Pretty-print messages. |
| 1603 | ------------ |
| 1604 | |
| 1605 | However, there is no particular reason to merge in one branch |
| 1606 | first and the other next, when what you have are a set of truly |
| 1607 | independent changes (if the order mattered, then they are not |
| 1608 | independent by definition). You could instead merge those two |
| 1609 | branches into the current branch at once. First let's undo what |
| 1610 | we just did and start over. We would want to get the master |
| 1611 | branch before these two merges by resetting it to 'master~2': |
| 1612 | |
| 1613 | ------------ |
| 1614 | $ git reset --hard master~2 |
| 1615 | ------------ |
| 1616 | |
Jonathan Nieder | db5d666 | 2008-07-03 01:06:23 -0500 | [diff] [blame] | 1617 | You can make sure `git show-branch` matches the state before |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 1618 | those two 'git merge' you just did. Then, instead of running |
| 1619 | two 'git merge' commands in a row, you would merge these two |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1620 | branch heads (this is known as 'making an Octopus'): |
| 1621 | |
| 1622 | ------------ |
Nicolas Pitre | c14261e | 2007-01-14 22:44:18 -0500 | [diff] [blame] | 1623 | $ git merge commit-fix diff-fix |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1624 | $ git show-branch |
| 1625 | ! [commit-fix] Fix commit message normalization. |
| 1626 | ! [diff-fix] Fix rename detection. |
| 1627 | * [master] Octopus merge of branches 'diff-fix' and 'commit-fix' |
| 1628 | --- |
| 1629 | - [master] Octopus merge of branches 'diff-fix' and 'commit-fix' |
| 1630 | + * [commit-fix] Fix commit message normalization. |
| 1631 | +* [diff-fix] Fix rename detection. |
| 1632 | +* [diff-fix~1] Better common substring algorithm. |
| 1633 | * [master~1] Release candidate #1 |
| 1634 | ++* [master~2] Pretty-print messages. |
| 1635 | ------------ |
| 1636 | |
Kristoffer Haugsbakk | c857c3a | 2016-12-09 16:51:11 +0100 | [diff] [blame] | 1637 | Note that you should not do Octopus just because you can. An octopus |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1638 | is a valid thing to do and often makes it easier to view the |
Nicolas Pitre | c14261e | 2007-01-14 22:44:18 -0500 | [diff] [blame] | 1639 | commit history if you are merging more than two independent |
J. Bruce Fields | 927a503 | 2006-01-22 23:57:25 -0500 | [diff] [blame] | 1640 | changes at the same time. However, if you have merge conflicts |
| 1641 | with any of the branches you are merging in and need to hand |
| 1642 | resolve, that is an indication that the development happened in |
| 1643 | those branches were not independent after all, and you should |
| 1644 | merge two at a time, documenting how you resolved the conflicts, |
| 1645 | and the reason why you preferred changes made in one side over |
| 1646 | the other. Otherwise it would make the project history harder |
| 1647 | to follow, not easier. |
Christian Couder | 497c833 | 2008-05-29 19:21:46 +0200 | [diff] [blame] | 1648 | |
| 1649 | SEE ALSO |
| 1650 | -------- |
Christian Couder | de07767 | 2008-11-14 13:26:47 +0100 | [diff] [blame] | 1651 | linkgit:gittutorial[7], |
| 1652 | linkgit:gittutorial-2[7], |
| 1653 | linkgit:gitcvs-migration[7], |
Christian Couder | 6e702c2 | 2008-11-17 16:43:04 +0100 | [diff] [blame] | 1654 | linkgit:git-help[1], |
Philip Oakley | 673151a | 2014-10-10 22:25:37 +0100 | [diff] [blame] | 1655 | linkgit:giteveryday[7], |
Christian Couder | 497c833 | 2008-05-29 19:21:46 +0200 | [diff] [blame] | 1656 | link:user-manual.html[The Git User's Manual] |
| 1657 | |
| 1658 | GIT |
| 1659 | --- |
Stefan Beller | 941b9c5 | 2017-02-08 17:29:30 -0800 | [diff] [blame] | 1660 | Part of the linkgit:git[1] suite |