Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 1 | Git User Manual |
Junio C Hamano | 21bc18b | 2014-01-10 20:33:07 | [diff] [blame] | 2 | =============== |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 3 | |
| 4 | Git is a fast distributed revision control system. |
| 5 | |
Junio C Hamano | a638742 | 2007-08-25 03:54:27 | [diff] [blame] | 6 | This manual is designed to be readable by someone with basic UNIX |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 7 | command-line skills, but no previous knowledge of Git. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 8 | |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 9 | <<repositories-and-branches>> and <<exploring-git-history>> explain how |
| 10 | to fetch and study a project using git--read these chapters to learn how |
| 11 | to build and test a particular version of a software project, search for |
| 12 | regressions, and so on. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 13 | |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 14 | People needing to do actual development will also want to read |
Junio C Hamano | ec87f52 | 2008-12-10 08:35:25 | [diff] [blame] | 15 | <<Developing-With-git>> and <<sharing-development>>. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 16 | |
| 17 | Further chapters cover more specialized topics. |
| 18 | |
| 19 | Comprehensive reference documentation is available through the man |
Junio C Hamano | f66ecee | 2008-11-17 18:25:43 | [diff] [blame] | 20 | pages, or linkgit:git-help[1] command. For example, for the command |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 21 | `git clone <repo>`, you can either use: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 22 | |
| 23 | ------------------------------------------------ |
| 24 | $ man git-clone |
| 25 | ------------------------------------------------ |
| 26 | |
Junio C Hamano | f66ecee | 2008-11-17 18:25:43 | [diff] [blame] | 27 | or: |
| 28 | |
| 29 | ------------------------------------------------ |
| 30 | $ git help clone |
| 31 | ------------------------------------------------ |
| 32 | |
| 33 | With the latter, you can use the manual viewer of your choice; see |
| 34 | linkgit:git-help[1] for more information. |
| 35 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 36 | See also <<git-quick-start>> for a brief overview of Git commands, |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 37 | without any explanation. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 38 | |
Junio C Hamano | f614c64 | 2007-06-11 01:21:54 | [diff] [blame] | 39 | Finally, see <<todo>> for ways that you can help make this manual more |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 40 | complete. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 41 | |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 42 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 43 | [[repositories-and-branches]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 44 | Repositories and Branches |
| 45 | ========================= |
| 46 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 47 | [[how-to-get-a-git-repository]] |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 48 | How to get a Git repository |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 49 | --------------------------- |
| 50 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 51 | It will be useful to have a Git repository to experiment with as you |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 52 | read this manual. |
| 53 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 54 | The best way to get one is by using the linkgit:git-clone[1] command to |
Junio C Hamano | 8b8b0f2 | 2007-08-26 22:10:26 | [diff] [blame] | 55 | download a copy of an existing repository. If you don't already have a |
| 56 | project in mind, here are some interesting examples: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 57 | |
| 58 | ------------------------------------------------ |
Junio C Hamano | 3a3357e | 2013-06-26 23:20:56 | [diff] [blame] | 59 | # Git itself (approx. 40MB download): |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 60 | $ git clone git://git.kernel.org/pub/scm/git/git.git |
Junio C Hamano | 3a3357e | 2013-06-26 23:20:56 | [diff] [blame] | 61 | # the Linux kernel (approx. 640MB download): |
| 62 | $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 63 | ------------------------------------------------ |
| 64 | |
| 65 | The initial clone may be time-consuming for a large project, but you |
| 66 | will only need to clone once. |
| 67 | |
Junio C Hamano | a195230 | 2013-07-01 21:31:18 | [diff] [blame] | 68 | The clone command creates a new directory named after the project |
| 69 | (`git` or `linux` in the examples above). After you cd into this |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 70 | directory, you will see that it contains a copy of the project files, |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 71 | called the <<def_working_tree,working tree>>, together with a special |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 72 | top-level directory named `.git`, which contains all the information |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 73 | about the history of the project. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 74 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 75 | [[how-to-check-out]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 76 | How to check out a different version of a project |
| 77 | ------------------------------------------------- |
| 78 | |
Junio C Hamano | 8b8b0f2 | 2007-08-26 22:10:26 | [diff] [blame] | 79 | Git is best thought of as a tool for storing the history of a collection |
| 80 | of files. It stores the history as a compressed collection of |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 81 | interrelated snapshots of the project's contents. In Git each such |
Junio C Hamano | 8b8b0f2 | 2007-08-26 22:10:26 | [diff] [blame] | 82 | version is called a <<def_commit,commit>>. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 83 | |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 84 | Those snapshots aren't necessarily all arranged in a single line from |
| 85 | oldest to newest; instead, work may simultaneously proceed along |
Junio C Hamano | 618bdde | 2008-01-02 10:51:08 | [diff] [blame] | 86 | parallel lines of development, called <<def_branch,branches>>, which may |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 87 | merge and diverge. |
| 88 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 89 | A single Git repository can track development on multiple branches. It |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 90 | does this by keeping a list of <<def_head,heads>> which reference the |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 91 | latest commit on each branch; the linkgit:git-branch[1] command shows |
Junio C Hamano | 3d5b41f | 2007-03-26 02:33:41 | [diff] [blame] | 92 | you the list of branch heads: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 93 | |
| 94 | ------------------------------------------------ |
| 95 | $ git branch |
| 96 | * master |
| 97 | ------------------------------------------------ |
| 98 | |
Junio C Hamano | 0e3cb53 | 2007-04-17 08:28:11 | [diff] [blame] | 99 | A freshly cloned repository contains a single branch head, by default |
| 100 | named "master", with the working directory initialized to the state of |
| 101 | the project referred to by that branch head. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 102 | |
Junio C Hamano | 3d5b41f | 2007-03-26 02:33:41 | [diff] [blame] | 103 | Most projects also use <<def_tag,tags>>. Tags, like heads, are |
| 104 | references into the project's history, and can be listed using the |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 105 | linkgit:git-tag[1] command: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 106 | |
| 107 | ------------------------------------------------ |
| 108 | $ git tag -l |
| 109 | v2.6.11 |
| 110 | v2.6.11-tree |
| 111 | v2.6.12 |
| 112 | v2.6.12-rc2 |
| 113 | v2.6.12-rc3 |
| 114 | v2.6.12-rc4 |
| 115 | v2.6.12-rc5 |
| 116 | v2.6.12-rc6 |
| 117 | v2.6.13 |
| 118 | ... |
| 119 | ------------------------------------------------ |
| 120 | |
| 121 | Tags are expected to always point at the same version of a project, |
Junio C Hamano | 3d5b41f | 2007-03-26 02:33:41 | [diff] [blame] | 122 | while heads are expected to advance as development progresses. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 123 | |
Junio C Hamano | 3d5b41f | 2007-03-26 02:33:41 | [diff] [blame] | 124 | Create a new branch head pointing to one of these versions and check it |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 125 | out using linkgit:git-checkout[1]: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 126 | |
| 127 | ------------------------------------------------ |
| 128 | $ git checkout -b new v2.6.13 |
| 129 | ------------------------------------------------ |
| 130 | |
| 131 | The working directory then reflects the contents that the project had |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 132 | when it was tagged v2.6.13, and linkgit:git-branch[1] shows two |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 133 | branches, with an asterisk marking the currently checked-out branch: |
| 134 | |
| 135 | ------------------------------------------------ |
| 136 | $ git branch |
| 137 | master |
| 138 | * new |
| 139 | ------------------------------------------------ |
| 140 | |
| 141 | If you decide that you'd rather see version 2.6.17, you can modify |
| 142 | the current branch to point at v2.6.17 instead, with |
| 143 | |
| 144 | ------------------------------------------------ |
| 145 | $ git reset --hard v2.6.17 |
| 146 | ------------------------------------------------ |
| 147 | |
Junio C Hamano | 3d5b41f | 2007-03-26 02:33:41 | [diff] [blame] | 148 | Note that if the current branch head was your only reference to a |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 149 | particular point in history, then resetting that branch may leave you |
Junio C Hamano | 3d5b41f | 2007-03-26 02:33:41 | [diff] [blame] | 150 | with no way to find the history it used to point to; so use this command |
| 151 | carefully. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 152 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 153 | [[understanding-commits]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 154 | Understanding History: Commits |
| 155 | ------------------------------ |
| 156 | |
| 157 | Every change in the history of a project is represented by a commit. |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 158 | The linkgit:git-show[1] command shows the most recent commit on the |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 159 | current branch: |
| 160 | |
| 161 | ------------------------------------------------ |
| 162 | $ git show |
Junio C Hamano | 8b8b0f2 | 2007-08-26 22:10:26 | [diff] [blame] | 163 | commit 17cf781661e6d38f737f15f53ab552f1e95960d7 |
| 164 | Author: Linus Torvalds <torvalds@ppc970.osdl.org.(none)> |
| 165 | Date: Tue Apr 19 14:11:06 2005 -0700 |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 166 | |
Junio C Hamano | 8b8b0f2 | 2007-08-26 22:10:26 | [diff] [blame] | 167 | Remove duplicate getenv(DB_ENVIRONMENT) call |
Junio C Hamano | a77a513 | 2007-06-08 16:13:44 | [diff] [blame] | 168 | |
Junio C Hamano | 8b8b0f2 | 2007-08-26 22:10:26 | [diff] [blame] | 169 | Noted by Tony Luck. |
Junio C Hamano | a77a513 | 2007-06-08 16:13:44 | [diff] [blame] | 170 | |
Junio C Hamano | 8b8b0f2 | 2007-08-26 22:10:26 | [diff] [blame] | 171 | diff --git a/init-db.c b/init-db.c |
| 172 | index 65898fa..b002dc6 100644 |
| 173 | --- a/init-db.c |
| 174 | +++ b/init-db.c |
| 175 | @@ -7,7 +7,7 @@ |
| 176 | |
| 177 | int main(int argc, char **argv) |
| 178 | { |
| 179 | - char *sha1_dir = getenv(DB_ENVIRONMENT), *path; |
| 180 | + char *sha1_dir, *path; |
| 181 | int len, i; |
| 182 | |
| 183 | if (mkdir(".git", 0755) < 0) { |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 184 | ------------------------------------------------ |
| 185 | |
| 186 | As you can see, a commit shows who made the latest change, what they |
| 187 | did, and why. |
| 188 | |
Junio C Hamano | aa83a7d | 2007-03-05 02:37:29 | [diff] [blame] | 189 | Every commit has a 40-hexdigit id, sometimes called the "object name" or the |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 190 | "SHA-1 id", shown on the first line of the `git show` output. You can usually |
Junio C Hamano | aa83a7d | 2007-03-05 02:37:29 | [diff] [blame] | 191 | refer to a commit by a shorter name, such as a tag or a branch name, but this |
| 192 | longer name can also be useful. Most importantly, it is a globally unique |
| 193 | name for this commit: so if you tell somebody else the object name (for |
| 194 | example in email), then you are guaranteed that name will refer to the same |
| 195 | commit in their repository that it does in yours (assuming their repository |
| 196 | has that commit at all). Since the object name is computed as a hash over the |
| 197 | contents of the commit, you are guaranteed that the commit can never change |
| 198 | without its name also changing. |
| 199 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 200 | In fact, in <<git-concepts>> we shall see that everything stored in Git |
Junio C Hamano | aa83a7d | 2007-03-05 02:37:29 | [diff] [blame] | 201 | history, including file data and directory contents, is stored in an object |
| 202 | with a name that is a hash of its contents. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 203 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 204 | [[understanding-reachability]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 205 | Understanding history: commits, parents, and reachability |
| 206 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 207 | |
| 208 | Every commit (except the very first commit in a project) also has a |
| 209 | parent commit which shows what happened before this commit. |
| 210 | Following the chain of parents will eventually take you back to the |
| 211 | beginning of the project. |
| 212 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 213 | However, the commits do not form a simple list; Git allows lines of |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 214 | development to diverge and then reconverge, and the point where two |
| 215 | lines of development reconverge is called a "merge". The commit |
| 216 | representing a merge can therefore have more than one parent, with |
| 217 | each parent representing the most recent commit on one of the lines |
| 218 | of development leading to that point. |
| 219 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 220 | The best way to see how this works is using the linkgit:gitk[1] |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 221 | command; running gitk now on a Git repository and looking for merge |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 222 | commits will help understand how Git organizes history. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 223 | |
| 224 | In the following, we say that commit X is "reachable" from commit Y |
| 225 | if commit X is an ancestor of commit Y. Equivalently, you could say |
Junio C Hamano | a638742 | 2007-08-25 03:54:27 | [diff] [blame] | 226 | that Y is a descendant of X, or that there is a chain of parents |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 227 | leading from commit Y to commit X. |
| 228 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 229 | [[history-diagrams]] |
Junio C Hamano | ee1e428 | 2007-02-04 08:32:04 | [diff] [blame] | 230 | Understanding history: History diagrams |
| 231 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 232 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 233 | We will sometimes represent Git history using diagrams like the one |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 234 | below. Commits are shown as "o", and the links between them with |
| 235 | lines drawn with - / and \. Time goes left to right: |
| 236 | |
Junio C Hamano | c51fede | 2007-03-12 07:29:20 | [diff] [blame] | 237 | |
| 238 | ................................................ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 239 | o--o--o <-- Branch A |
| 240 | / |
| 241 | o--o--o <-- master |
| 242 | \ |
| 243 | o--o--o <-- Branch B |
Junio C Hamano | c51fede | 2007-03-12 07:29:20 | [diff] [blame] | 244 | ................................................ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 245 | |
| 246 | If we need to talk about a particular commit, the character "o" may |
| 247 | be replaced with another letter or number. |
| 248 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 249 | [[what-is-a-branch]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 250 | Understanding history: What is a branch? |
| 251 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 252 | |
Junio C Hamano | 3d5b41f | 2007-03-26 02:33:41 | [diff] [blame] | 253 | When we need to be precise, we will use the word "branch" to mean a line |
| 254 | of development, and "branch head" (or just "head") to mean a reference |
| 255 | to the most recent commit on a branch. In the example above, the branch |
| 256 | head named "A" is a pointer to one particular commit, but we refer to |
| 257 | the line of three commits leading up to that point as all being part of |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 258 | "branch A". |
| 259 | |
Junio C Hamano | 3d5b41f | 2007-03-26 02:33:41 | [diff] [blame] | 260 | However, when no confusion will result, we often just use the term |
| 261 | "branch" both for branches and for branch heads. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 262 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 263 | [[manipulating-branches]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 264 | Manipulating branches |
| 265 | --------------------- |
| 266 | |
| 267 | Creating, deleting, and modifying branches is quick and easy; here's |
| 268 | a summary of the commands: |
| 269 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 270 | `git branch`:: |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 271 | list all branches. |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 272 | `git branch <branch>`:: |
| 273 | create a new branch named `<branch>`, referencing the same |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 274 | point in history as the current branch. |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 275 | `git branch <branch> <start-point>`:: |
| 276 | create a new branch named `<branch>`, referencing |
| 277 | `<start-point>`, which may be specified any way you like, |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 278 | including using a branch name or a tag name. |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 279 | `git branch -d <branch>`:: |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 280 | delete the branch `<branch>`; if the branch is not fully |
| 281 | merged in its upstream branch or contained in the current branch, |
| 282 | this command will fail with a warning. |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 283 | `git branch -D <branch>`:: |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 284 | delete the branch `<branch>` irrespective of its merged status. |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 285 | `git checkout <branch>`:: |
| 286 | make the current branch `<branch>`, updating the working |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 287 | directory to reflect the version referenced by `<branch>`. |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 288 | `git checkout -b <new> <start-point>`:: |
| 289 | create a new branch `<new>` referencing `<start-point>`, and |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 290 | check it out. |
| 291 | |
Junio C Hamano | 0e3cb53 | 2007-04-17 08:28:11 | [diff] [blame] | 292 | The special symbol "HEAD" can always be used to refer to the current |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 293 | branch. In fact, Git uses a file named `HEAD` in the `.git` directory |
| 294 | to remember which branch is current: |
Junio C Hamano | 0e3cb53 | 2007-04-17 08:28:11 | [diff] [blame] | 295 | |
| 296 | ------------------------------------------------ |
| 297 | $ cat .git/HEAD |
| 298 | ref: refs/heads/master |
| 299 | ------------------------------------------------ |
| 300 | |
| 301 | [[detached-head]] |
| 302 | Examining an old version without creating a new branch |
| 303 | ------------------------------------------------------ |
| 304 | |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 305 | The `git checkout` command normally expects a branch head, but will also |
Junio C Hamano | 0e3cb53 | 2007-04-17 08:28:11 | [diff] [blame] | 306 | accept an arbitrary commit; for example, you can check out the commit |
| 307 | referenced by a tag: |
| 308 | |
| 309 | ------------------------------------------------ |
| 310 | $ git checkout v2.6.17 |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 311 | Note: checking out 'v2.6.17'. |
| 312 | |
| 313 | You are in 'detached HEAD' state. You can look around, make experimental |
| 314 | changes and commit them, and you can discard any commits you make in this |
| 315 | state without impacting any branches by performing another checkout. |
| 316 | |
| 317 | If you want to create a new branch to retain commits you create, you may |
| 318 | do so (now or later) by using -b with the checkout command again. Example: |
| 319 | |
| 320 | git checkout -b new_branch_name |
| 321 | |
Junio C Hamano | 0e3cb53 | 2007-04-17 08:28:11 | [diff] [blame] | 322 | HEAD is now at 427abfa... Linux v2.6.17 |
| 323 | ------------------------------------------------ |
| 324 | |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 325 | The HEAD then refers to the SHA-1 of the commit instead of to a branch, |
Junio C Hamano | 0e3cb53 | 2007-04-17 08:28:11 | [diff] [blame] | 326 | and git branch shows that you are no longer on a branch: |
| 327 | |
| 328 | ------------------------------------------------ |
| 329 | $ cat .git/HEAD |
| 330 | 427abfa28afedffadfca9dd8b067eb6d36bac53f |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 331 | $ git branch |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 332 | * (detached from v2.6.17) |
Junio C Hamano | 0e3cb53 | 2007-04-17 08:28:11 | [diff] [blame] | 333 | master |
| 334 | ------------------------------------------------ |
| 335 | |
| 336 | In this case we say that the HEAD is "detached". |
| 337 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 338 | This is an easy way to check out a particular version without having to |
| 339 | make up a name for the new branch. You can still create a new branch |
| 340 | (or tag) for this version later if you decide to. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 341 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 342 | [[examining-remote-branches]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 343 | Examining branches from a remote repository |
| 344 | ------------------------------------------- |
| 345 | |
| 346 | The "master" branch that was created at the time you cloned is a copy |
| 347 | of the HEAD in the repository that you cloned from. That repository |
| 348 | may also have had other branches, though, and your local repository |
Junio C Hamano | 97bcb48 | 2010-11-25 03:16:07 | [diff] [blame] | 349 | keeps branches which track each of those remote branches, called |
| 350 | remote-tracking branches, which you |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 351 | can view using the `-r` option to linkgit:git-branch[1]: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 352 | |
| 353 | ------------------------------------------------ |
| 354 | $ git branch -r |
| 355 | origin/HEAD |
| 356 | origin/html |
| 357 | origin/maint |
| 358 | origin/man |
| 359 | origin/master |
| 360 | origin/next |
| 361 | origin/pu |
| 362 | origin/todo |
| 363 | ------------------------------------------------ |
| 364 | |
Junio C Hamano | 97bcb48 | 2010-11-25 03:16:07 | [diff] [blame] | 365 | In this example, "origin" is called a remote repository, or "remote" |
| 366 | for short. The branches of this repository are called "remote |
| 367 | branches" from our point of view. The remote-tracking branches listed |
| 368 | above were created based on the remote branches at clone time and will |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 369 | be updated by `git fetch` (hence `git pull`) and `git push`. See |
Junio C Hamano | 97bcb48 | 2010-11-25 03:16:07 | [diff] [blame] | 370 | <<Updating-a-repository-With-git-fetch>> for details. |
| 371 | |
| 372 | You might want to build on one of these remote-tracking branches |
| 373 | on a branch of your own, just as you would for a tag: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 374 | |
| 375 | ------------------------------------------------ |
| 376 | $ git checkout -b my-todo-copy origin/todo |
| 377 | ------------------------------------------------ |
| 378 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 379 | You can also check out `origin/todo` directly to examine it or |
Junio C Hamano | 97bcb48 | 2010-11-25 03:16:07 | [diff] [blame] | 380 | write a one-off patch. See <<detached-head,detached head>>. |
| 381 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 382 | Note that the name "origin" is just the name that Git uses by default |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 383 | to refer to the repository that you cloned from. |
| 384 | |
| 385 | [[how-git-stores-references]] |
| 386 | Naming branches, tags, and other references |
| 387 | ------------------------------------------- |
| 388 | |
| 389 | Branches, remote-tracking branches, and tags are all references to |
| 390 | commits. All references are named with a slash-separated path name |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 391 | starting with `refs`; the names we've been using so far are actually |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 392 | shorthand: |
| 393 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 394 | - The branch `test` is short for `refs/heads/test`. |
| 395 | - The tag `v2.6.18` is short for `refs/tags/v2.6.18`. |
| 396 | - `origin/master` is short for `refs/remotes/origin/master`. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 397 | |
| 398 | The full name is occasionally useful if, for example, there ever |
| 399 | exists a tag and a branch with the same name. |
| 400 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 401 | (Newly created refs are actually stored in the `.git/refs` directory, |
Junio C Hamano | 9810d63 | 2007-09-24 01:05:34 | [diff] [blame] | 402 | under the path given by their name. However, for efficiency reasons |
| 403 | they may also be packed together in a single file; see |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 404 | linkgit:git-pack-refs[1]). |
Junio C Hamano | 9810d63 | 2007-09-24 01:05:34 | [diff] [blame] | 405 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 406 | As another useful shortcut, the "HEAD" of a repository can be referred |
| 407 | to just using the name of that repository. So, for example, "origin" |
| 408 | is usually a shortcut for the HEAD branch in the repository "origin". |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 409 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 410 | For the complete list of paths which Git checks for references, and |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 411 | the order it uses to decide which to choose when there are multiple |
| 412 | references with the same shorthand name, see the "SPECIFYING |
Junio C Hamano | c27b733 | 2010-10-14 04:37:28 | [diff] [blame] | 413 | REVISIONS" section of linkgit:gitrevisions[7]. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 414 | |
Junio C Hamano | ec87f52 | 2008-12-10 08:35:25 | [diff] [blame] | 415 | [[Updating-a-repository-With-git-fetch]] |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 416 | Updating a repository with git fetch |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 417 | ------------------------------------ |
| 418 | |
Junio C Hamano | c8c398a | 2014-06-16 21:14:05 | [diff] [blame] | 419 | After you clone a repository and commit a few changes of your own, you |
| 420 | may wish to check the original repository for updates. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 421 | |
Junio C Hamano | c8c398a | 2014-06-16 21:14:05 | [diff] [blame] | 422 | The `git-fetch` command, with no arguments, will update all of the |
| 423 | remote-tracking branches to the latest version found in the original |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 424 | repository. It will not touch any of your own branches--not even the |
| 425 | "master" branch that was created for you on clone. |
| 426 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 427 | [[fetching-branches]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 428 | Fetching branches from other repositories |
| 429 | ----------------------------------------- |
| 430 | |
| 431 | You can also track branches from repositories other than the one you |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 432 | cloned from, using linkgit:git-remote[1]: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 433 | |
| 434 | ------------------------------------------------- |
Junio C Hamano | a195230 | 2013-07-01 21:31:18 | [diff] [blame] | 435 | $ git remote add staging git://git.kernel.org/.../gregkh/staging.git |
| 436 | $ git fetch staging |
| 437 | ... |
| 438 | From git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging |
| 439 | * [new branch] master -> staging/master |
| 440 | * [new branch] staging-linus -> staging/staging-linus |
| 441 | * [new branch] staging-next -> staging/staging-next |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 442 | ------------------------------------------------- |
| 443 | |
| 444 | New remote-tracking branches will be stored under the shorthand name |
Junio C Hamano | a195230 | 2013-07-01 21:31:18 | [diff] [blame] | 445 | that you gave `git remote add`, in this case `staging`: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 446 | |
| 447 | ------------------------------------------------- |
| 448 | $ git branch -r |
Junio C Hamano | a195230 | 2013-07-01 21:31:18 | [diff] [blame] | 449 | origin/HEAD -> origin/master |
| 450 | origin/master |
| 451 | staging/master |
| 452 | staging/staging-linus |
| 453 | staging/staging-next |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 454 | ------------------------------------------------- |
| 455 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 456 | If you run `git fetch <remote>` later, the remote-tracking branches |
| 457 | for the named `<remote>` will be updated. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 458 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 459 | If you examine the file `.git/config`, you will see that Git has added |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 460 | a new stanza: |
| 461 | |
| 462 | ------------------------------------------------- |
| 463 | $ cat .git/config |
| 464 | ... |
Junio C Hamano | a195230 | 2013-07-01 21:31:18 | [diff] [blame] | 465 | [remote "staging"] |
| 466 | url = git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging.git |
| 467 | fetch = +refs/heads/*:refs/remotes/staging/* |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 468 | ... |
| 469 | ------------------------------------------------- |
| 470 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 471 | This is what causes Git to track the remote's branches; you may modify |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 472 | or delete these configuration options by editing `.git/config` with a |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 473 | text editor. (See the "CONFIGURATION FILE" section of |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 474 | linkgit:git-config[1] for details.) |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 475 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 476 | [[exploring-git-history]] |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 477 | Exploring Git history |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 478 | ===================== |
| 479 | |
| 480 | Git is best thought of as a tool for storing the history of a |
| 481 | collection of files. It does this by storing compressed snapshots of |
Junio C Hamano | cc13f55 | 2007-07-24 08:59:43 | [diff] [blame] | 482 | the contents of a file hierarchy, together with "commits" which show |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 483 | the relationships between these snapshots. |
| 484 | |
| 485 | Git provides extremely flexible and fast tools for exploring the |
| 486 | history of a project. |
| 487 | |
Junio C Hamano | 39381a7 | 2007-02-02 07:35:15 | [diff] [blame] | 488 | We start with one specialized tool that is useful for finding the |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 489 | commit that introduced a bug into a project. |
| 490 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 491 | [[using-bisect]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 492 | How to use bisect to find a regression |
| 493 | -------------------------------------- |
| 494 | |
| 495 | Suppose version 2.6.18 of your project worked, but the version at |
| 496 | "master" crashes. Sometimes the best way to find the cause of such a |
| 497 | regression is to perform a brute-force search through the project's |
| 498 | history to find the particular commit that caused the problem. The |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 499 | linkgit:git-bisect[1] command can help you do this: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 500 | |
| 501 | ------------------------------------------------- |
| 502 | $ git bisect start |
| 503 | $ git bisect good v2.6.18 |
| 504 | $ git bisect bad master |
| 505 | Bisecting: 3537 revisions left to test after this |
| 506 | [65934a9a028b88e83e2b0f8b36618fe503349f8e] BLOCK: Make USB storage depend on SCSI rather than selecting it [try #6] |
| 507 | ------------------------------------------------- |
| 508 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 509 | If you run `git branch` at this point, you'll see that Git has |
Junio C Hamano | 9e39507 | 2008-07-31 22:11:21 | [diff] [blame] | 510 | temporarily moved you in "(no branch)". HEAD is now detached from any |
| 511 | branch and points directly to a commit (with commit id 65934...) that |
| 512 | is reachable from "master" but not from v2.6.18. Compile and test it, |
| 513 | and see whether it crashes. Assume it does crash. Then: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 514 | |
| 515 | ------------------------------------------------- |
| 516 | $ git bisect bad |
| 517 | Bisecting: 1769 revisions left to test after this |
| 518 | [7eff82c8b1511017ae605f0c99ac275a7e21b867] i2c-core: Drop useless bitmaskings |
| 519 | ------------------------------------------------- |
| 520 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 521 | checks out an older version. Continue like this, telling Git at each |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 522 | stage whether the version it gives you is good or bad, and notice |
| 523 | that the number of revisions left to test is cut approximately in |
| 524 | half each time. |
| 525 | |
| 526 | After about 13 tests (in this case), it will output the commit id of |
| 527 | the guilty commit. You can then examine the commit with |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 528 | linkgit:git-show[1], find out who wrote it, and mail them your bug |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 529 | report with the commit id. Finally, run |
| 530 | |
| 531 | ------------------------------------------------- |
| 532 | $ git bisect reset |
| 533 | ------------------------------------------------- |
| 534 | |
Junio C Hamano | 9e39507 | 2008-07-31 22:11:21 | [diff] [blame] | 535 | to return you to the branch you were on before. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 536 | |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 537 | Note that the version which `git bisect` checks out for you at each |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 538 | point is just a suggestion, and you're free to try a different |
| 539 | version if you think it would be a good idea. For example, |
| 540 | occasionally you may land on a commit that broke something unrelated; |
| 541 | run |
| 542 | |
| 543 | ------------------------------------------------- |
Junio C Hamano | 4c6aa8a | 2007-04-04 08:56:37 | [diff] [blame] | 544 | $ git bisect visualize |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 545 | ------------------------------------------------- |
| 546 | |
| 547 | which will run gitk and label the commit it chose with a marker that |
Junio C Hamano | d32738e | 2008-07-09 19:53:42 | [diff] [blame] | 548 | says "bisect". Choose a safe-looking commit nearby, note its commit |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 549 | id, and check it out with: |
| 550 | |
| 551 | ------------------------------------------------- |
| 552 | $ git reset --hard fb47ddb2db... |
| 553 | ------------------------------------------------- |
| 554 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 555 | then test, run `bisect good` or `bisect bad` as appropriate, and |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 556 | continue. |
| 557 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 558 | Instead of `git bisect visualize` and then `git reset --hard |
| 559 | fb47ddb2db...`, you might just want to tell Git that you want to skip |
Junio C Hamano | 9e39507 | 2008-07-31 22:11:21 | [diff] [blame] | 560 | the current commit: |
| 561 | |
| 562 | ------------------------------------------------- |
| 563 | $ git bisect skip |
| 564 | ------------------------------------------------- |
| 565 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 566 | In this case, though, Git may not eventually be able to tell the first |
Junio C Hamano | 610d176 | 2008-11-28 06:27:13 | [diff] [blame] | 567 | bad one between some first skipped commits and a later bad commit. |
Junio C Hamano | 9e39507 | 2008-07-31 22:11:21 | [diff] [blame] | 568 | |
| 569 | There are also ways to automate the bisecting process if you have a |
| 570 | test script that can tell a good from a bad commit. See |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 571 | linkgit:git-bisect[1] for more information about this and other `git |
| 572 | bisect` features. |
Junio C Hamano | 9e39507 | 2008-07-31 22:11:21 | [diff] [blame] | 573 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 574 | [[naming-commits]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 575 | Naming commits |
| 576 | -------------- |
| 577 | |
| 578 | We have seen several ways of naming commits already: |
| 579 | |
| 580 | - 40-hexdigit object name |
| 581 | - branch name: refers to the commit at the head of the given |
| 582 | branch |
| 583 | - tag name: refers to the commit pointed to by the given tag |
| 584 | (we've seen branches and tags are special cases of |
| 585 | <<how-git-stores-references,references>>). |
| 586 | - HEAD: refers to the head of the current branch |
| 587 | |
| 588 | There are many more; see the "SPECIFYING REVISIONS" section of the |
Junio C Hamano | c27b733 | 2010-10-14 04:37:28 | [diff] [blame] | 589 | linkgit:gitrevisions[7] man page for the complete list of ways to |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 590 | name revisions. Some examples: |
| 591 | |
| 592 | ------------------------------------------------- |
| 593 | $ git show fb47ddb2 # the first few characters of the object name |
| 594 | # are usually enough to specify it uniquely |
| 595 | $ git show HEAD^ # the parent of the HEAD commit |
| 596 | $ git show HEAD^^ # the grandparent |
| 597 | $ git show HEAD~4 # the great-great-grandparent |
| 598 | ------------------------------------------------- |
| 599 | |
| 600 | Recall that merge commits may have more than one parent; by default, |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 601 | `^` and `~` follow the first parent listed in the commit, but you can |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 602 | also choose: |
| 603 | |
| 604 | ------------------------------------------------- |
| 605 | $ git show HEAD^1 # show the first parent of HEAD |
| 606 | $ git show HEAD^2 # show the second parent of HEAD |
| 607 | ------------------------------------------------- |
| 608 | |
| 609 | In addition to HEAD, there are several other special names for |
| 610 | commits: |
| 611 | |
| 612 | Merges (to be discussed later), as well as operations such as |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 613 | `git reset`, which change the currently checked-out commit, generally |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 614 | set ORIG_HEAD to the value HEAD had before the current operation. |
| 615 | |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 616 | The `git fetch` operation always stores the head of the last fetched |
| 617 | branch in FETCH_HEAD. For example, if you run `git fetch` without |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 618 | specifying a local branch as the target of the operation |
| 619 | |
| 620 | ------------------------------------------------- |
| 621 | $ git fetch git://example.com/proj.git theirbranch |
| 622 | ------------------------------------------------- |
| 623 | |
| 624 | the fetched commits will still be available from FETCH_HEAD. |
| 625 | |
| 626 | When we discuss merges we'll also see the special name MERGE_HEAD, |
| 627 | which refers to the other branch that we're merging in to the current |
| 628 | branch. |
| 629 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 630 | The linkgit:git-rev-parse[1] command is a low-level command that is |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 631 | occasionally useful for translating some name for a commit to the object |
| 632 | name for that commit: |
| 633 | |
| 634 | ------------------------------------------------- |
| 635 | $ git rev-parse origin |
| 636 | e05db0fd4f31dde7005f075a84f96b360d05984b |
| 637 | ------------------------------------------------- |
| 638 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 639 | [[creating-tags]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 640 | Creating tags |
| 641 | ------------- |
| 642 | |
| 643 | We can also create a tag to refer to a particular commit; after |
| 644 | running |
| 645 | |
| 646 | ------------------------------------------------- |
Junio C Hamano | 4c6aa8a | 2007-04-04 08:56:37 | [diff] [blame] | 647 | $ git tag stable-1 1b2e1d63ff |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 648 | ------------------------------------------------- |
| 649 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 650 | You can use `stable-1` to refer to the commit 1b2e1d63ff. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 651 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 652 | This creates a "lightweight" tag. If you would also like to include a |
| 653 | comment with the tag, and possibly sign it cryptographically, then you |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 654 | should create a tag object instead; see the linkgit:git-tag[1] man page |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 655 | for details. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 656 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 657 | [[browsing-revisions]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 658 | Browsing revisions |
| 659 | ------------------ |
| 660 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 661 | The linkgit:git-log[1] command can show lists of commits. On its |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 662 | own, it shows all commits reachable from the parent commit; but you |
| 663 | can also make more specific requests: |
| 664 | |
| 665 | ------------------------------------------------- |
| 666 | $ git log v2.5.. # commits since (not reachable from) v2.5 |
| 667 | $ git log test..master # commits reachable from master but not test |
| 668 | $ git log master..test # ...reachable from test but not master |
| 669 | $ git log master...test # ...reachable from either test or master, |
| 670 | # but not both |
| 671 | $ git log --since="2 weeks ago" # commits from the last 2 weeks |
| 672 | $ git log Makefile # commits which modify Makefile |
| 673 | $ git log fs/ # ... which modify any file under fs/ |
| 674 | $ git log -S'foo()' # commits which add or remove any file data |
| 675 | # matching the string 'foo()' |
| 676 | ------------------------------------------------- |
| 677 | |
| 678 | And of course you can combine all of these; the following finds |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 679 | commits since v2.5 which touch the `Makefile` or any file under `fs`: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 680 | |
| 681 | ------------------------------------------------- |
| 682 | $ git log v2.5.. Makefile fs/ |
| 683 | ------------------------------------------------- |
| 684 | |
| 685 | You can also ask git log to show patches: |
| 686 | |
| 687 | ------------------------------------------------- |
| 688 | $ git log -p |
| 689 | ------------------------------------------------- |
| 690 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 691 | See the `--pretty` option in the linkgit:git-log[1] man page for more |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 692 | display options. |
| 693 | |
| 694 | Note that git log starts with the most recent commit and works |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 695 | backwards through the parents; however, since Git history can contain |
Junio C Hamano | ee1e428 | 2007-02-04 08:32:04 | [diff] [blame] | 696 | multiple independent lines of development, the particular order that |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 697 | commits are listed in may be somewhat arbitrary. |
| 698 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 699 | [[generating-diffs]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 700 | Generating diffs |
| 701 | ---------------- |
| 702 | |
| 703 | You can generate diffs between any two versions using |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 704 | linkgit:git-diff[1]: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 705 | |
| 706 | ------------------------------------------------- |
| 707 | $ git diff master..test |
| 708 | ------------------------------------------------- |
| 709 | |
Junio C Hamano | 393e57f | 2007-11-20 04:53:25 | [diff] [blame] | 710 | That will produce the diff between the tips of the two branches. If |
| 711 | you'd prefer to find the diff from their common ancestor to test, you |
| 712 | can use three dots instead of two: |
| 713 | |
| 714 | ------------------------------------------------- |
| 715 | $ git diff master...test |
| 716 | ------------------------------------------------- |
| 717 | |
| 718 | Sometimes what you want instead is a set of patches; for this you can |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 719 | use linkgit:git-format-patch[1]: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 720 | |
| 721 | ------------------------------------------------- |
| 722 | $ git format-patch master..test |
| 723 | ------------------------------------------------- |
| 724 | |
| 725 | will generate a file with a patch for each commit reachable from test |
Junio C Hamano | 393e57f | 2007-11-20 04:53:25 | [diff] [blame] | 726 | but not from master. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 727 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 728 | [[viewing-old-file-versions]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 729 | Viewing old file versions |
| 730 | ------------------------- |
| 731 | |
| 732 | You can always view an old version of a file by just checking out the |
| 733 | correct revision first. But sometimes it is more convenient to be |
| 734 | able to view an old version of a single file without checking |
| 735 | anything out; this command does that: |
| 736 | |
| 737 | ------------------------------------------------- |
| 738 | $ git show v2.5:fs/locks.c |
| 739 | ------------------------------------------------- |
| 740 | |
| 741 | Before the colon may be anything that names a commit, and after it |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 742 | may be any path to a file tracked by Git. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 743 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 744 | [[history-examples]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 745 | Examples |
| 746 | -------- |
| 747 | |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 748 | [[counting-commits-on-a-branch]] |
| 749 | Counting the number of commits on a branch |
| 750 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 751 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 752 | Suppose you want to know how many commits you've made on `mybranch` |
| 753 | since it diverged from `origin`: |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 754 | |
| 755 | ------------------------------------------------- |
| 756 | $ git log --pretty=oneline origin..mybranch | wc -l |
| 757 | ------------------------------------------------- |
| 758 | |
| 759 | Alternatively, you may often see this sort of thing done with the |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 760 | lower-level command linkgit:git-rev-list[1], which just lists the SHA-1's |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 761 | of all the given commits: |
| 762 | |
| 763 | ------------------------------------------------- |
| 764 | $ git rev-list origin..mybranch | wc -l |
| 765 | ------------------------------------------------- |
| 766 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 767 | [[checking-for-equal-branches]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 768 | Check whether two branches point at the same history |
| 769 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 770 | |
| 771 | Suppose you want to check whether two branches point at the same point |
| 772 | in history. |
| 773 | |
| 774 | ------------------------------------------------- |
| 775 | $ git diff origin..master |
| 776 | ------------------------------------------------- |
| 777 | |
| 778 | will tell you whether the contents of the project are the same at the |
| 779 | two branches; in theory, however, it's possible that the same project |
| 780 | contents could have been arrived at by two different historical |
| 781 | routes. You could compare the object names: |
| 782 | |
| 783 | ------------------------------------------------- |
| 784 | $ git rev-list origin |
| 785 | e05db0fd4f31dde7005f075a84f96b360d05984b |
| 786 | $ git rev-list master |
| 787 | e05db0fd4f31dde7005f075a84f96b360d05984b |
| 788 | ------------------------------------------------- |
| 789 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 790 | Or you could recall that the `...` operator selects all commits |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 791 | reachable from either one reference or the other but not |
Junio C Hamano | 8c5696d | 2013-02-11 05:35:00 | [diff] [blame] | 792 | both; so |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 793 | |
| 794 | ------------------------------------------------- |
| 795 | $ git log origin...master |
| 796 | ------------------------------------------------- |
| 797 | |
| 798 | will return no commits when the two branches are equal. |
| 799 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 800 | [[finding-tagged-descendants]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 801 | Find first tagged version including a given fix |
| 802 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 803 | |
| 804 | Suppose you know that the commit e05db0fd fixed a certain problem. |
| 805 | You'd like to find the earliest tagged release that contains that |
| 806 | fix. |
| 807 | |
| 808 | Of course, there may be more than one answer--if the history branched |
| 809 | after commit e05db0fd, then there could be multiple "earliest" tagged |
| 810 | releases. |
| 811 | |
| 812 | You could just visually inspect the commits since e05db0fd: |
| 813 | |
| 814 | ------------------------------------------------- |
| 815 | $ gitk e05db0fd.. |
| 816 | ------------------------------------------------- |
| 817 | |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 818 | or you can use linkgit:git-name-rev[1], which will give the commit a |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 819 | name based on any tag it finds pointing to one of the commit's |
| 820 | descendants: |
| 821 | |
| 822 | ------------------------------------------------- |
Junio C Hamano | 4c6aa8a | 2007-04-04 08:56:37 | [diff] [blame] | 823 | $ git name-rev --tags e05db0fd |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 824 | e05db0fd tags/v1.5.0-rc1^0~23 |
| 825 | ------------------------------------------------- |
| 826 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 827 | The linkgit:git-describe[1] command does the opposite, naming the |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 828 | revision using a tag on which the given commit is based: |
| 829 | |
| 830 | ------------------------------------------------- |
| 831 | $ git describe e05db0fd |
Junio C Hamano | 4c6aa8a | 2007-04-04 08:56:37 | [diff] [blame] | 832 | v1.5.0-rc0-260-ge05db0f |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 833 | ------------------------------------------------- |
| 834 | |
| 835 | but that may sometimes help you guess which tags might come after the |
| 836 | given commit. |
| 837 | |
| 838 | If you just want to verify whether a given tagged version contains a |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 839 | given commit, you could use linkgit:git-merge-base[1]: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 840 | |
| 841 | ------------------------------------------------- |
| 842 | $ git merge-base e05db0fd v1.5.0-rc1 |
| 843 | e05db0fd4f31dde7005f075a84f96b360d05984b |
| 844 | ------------------------------------------------- |
| 845 | |
| 846 | The merge-base command finds a common ancestor of the given commits, |
| 847 | and always returns one or the other in the case where one is a |
| 848 | descendant of the other; so the above output shows that e05db0fd |
| 849 | actually is an ancestor of v1.5.0-rc1. |
| 850 | |
| 851 | Alternatively, note that |
| 852 | |
| 853 | ------------------------------------------------- |
| 854 | $ git log v1.5.0-rc1..e05db0fd |
| 855 | ------------------------------------------------- |
| 856 | |
| 857 | will produce empty output if and only if v1.5.0-rc1 includes e05db0fd, |
| 858 | because it outputs only commits that are not reachable from v1.5.0-rc1. |
| 859 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 860 | As yet another alternative, the linkgit:git-show-branch[1] command lists |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 861 | the commits reachable from its arguments with a display on the left-hand |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 862 | side that indicates which arguments that commit is reachable from. |
| 863 | So, if you run something like |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 864 | |
| 865 | ------------------------------------------------- |
| 866 | $ git show-branch e05db0fd v1.5.0-rc0 v1.5.0-rc1 v1.5.0-rc2 |
| 867 | ! [e05db0fd] Fix warnings in sha1_file.c - use C99 printf format if |
| 868 | available |
| 869 | ! [v1.5.0-rc0] GIT v1.5.0 preview |
| 870 | ! [v1.5.0-rc1] GIT v1.5.0-rc1 |
| 871 | ! [v1.5.0-rc2] GIT v1.5.0-rc2 |
| 872 | ... |
| 873 | ------------------------------------------------- |
| 874 | |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 875 | then a line like |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 876 | |
| 877 | ------------------------------------------------- |
| 878 | + ++ [e05db0fd] Fix warnings in sha1_file.c - use C99 printf format if |
| 879 | available |
| 880 | ------------------------------------------------- |
| 881 | |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 882 | shows that e05db0fd is reachable from itself, from v1.5.0-rc1, |
| 883 | and from v1.5.0-rc2, and not from v1.5.0-rc0. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 884 | |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 885 | [[showing-commits-unique-to-a-branch]] |
| 886 | Showing commits unique to a given branch |
| 887 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 888 | |
| 889 | Suppose you would like to see all the commits reachable from the branch |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 890 | head named `master` but not from any other head in your repository. |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 891 | |
| 892 | We can list all the heads in this repository with |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 893 | linkgit:git-show-ref[1]: |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 894 | |
| 895 | ------------------------------------------------- |
| 896 | $ git show-ref --heads |
| 897 | bf62196b5e363d73353a9dcf094c59595f3153b7 refs/heads/core-tutorial |
| 898 | db768d5504c1bb46f63ee9d6e1772bd047e05bf9 refs/heads/maint |
| 899 | a07157ac624b2524a059a3414e99f6f44bebc1e7 refs/heads/master |
| 900 | 24dbc180ea14dc1aebe09f14c8ecf32010690627 refs/heads/tutorial-2 |
| 901 | 1e87486ae06626c2f31eaa63d26fc0fd646c8af2 refs/heads/tutorial-fixes |
| 902 | ------------------------------------------------- |
| 903 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 904 | We can get just the branch-head names, and remove `master`, with |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 905 | the help of the standard utilities cut and grep: |
| 906 | |
| 907 | ------------------------------------------------- |
| 908 | $ git show-ref --heads | cut -d' ' -f2 | grep -v '^refs/heads/master' |
| 909 | refs/heads/core-tutorial |
| 910 | refs/heads/maint |
| 911 | refs/heads/tutorial-2 |
| 912 | refs/heads/tutorial-fixes |
| 913 | ------------------------------------------------- |
| 914 | |
| 915 | And then we can ask to see all the commits reachable from master |
| 916 | but not from these other heads: |
| 917 | |
| 918 | ------------------------------------------------- |
| 919 | $ gitk master --not $( git show-ref --heads | cut -d' ' -f2 | |
| 920 | grep -v '^refs/heads/master' ) |
| 921 | ------------------------------------------------- |
| 922 | |
| 923 | Obviously, endless variations are possible; for example, to see all |
| 924 | commits reachable from some head but not from any tag in the repository: |
| 925 | |
| 926 | ------------------------------------------------- |
Junio C Hamano | 591dc6a | 2007-05-29 09:18:19 | [diff] [blame] | 927 | $ gitk $( git show-ref --heads ) --not $( git show-ref --tags ) |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 928 | ------------------------------------------------- |
| 929 | |
Junio C Hamano | c27b733 | 2010-10-14 04:37:28 | [diff] [blame] | 930 | (See linkgit:gitrevisions[7] for explanations of commit-selecting |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 931 | syntax such as `--not`.) |
| 932 | |
| 933 | [[making-a-release]] |
| 934 | Creating a changelog and tarball for a software release |
| 935 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 936 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 937 | The linkgit:git-archive[1] command can create a tar or zip archive from |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 938 | any version of a project; for example: |
| 939 | |
| 940 | ------------------------------------------------- |
Junio C Hamano | 2da4ac4 | 2013-02-19 00:41:17 | [diff] [blame] | 941 | $ git archive -o latest.tar.gz --prefix=project/ HEAD |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 942 | ------------------------------------------------- |
| 943 | |
Junio C Hamano | 2da4ac4 | 2013-02-19 00:41:17 | [diff] [blame] | 944 | will use HEAD to produce a gzipped tar archive in which each filename |
| 945 | is preceded by `project/`. The output file format is inferred from |
| 946 | the output file extension if possible, see linkgit:git-archive[1] for |
| 947 | details. |
| 948 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 949 | Versions of Git older than 1.7.7 don't know about the `tar.gz` format, |
Junio C Hamano | 2da4ac4 | 2013-02-19 00:41:17 | [diff] [blame] | 950 | you'll need to use gzip explicitly: |
| 951 | |
| 952 | ------------------------------------------------- |
| 953 | $ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz |
| 954 | ------------------------------------------------- |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 955 | |
| 956 | If you're releasing a new version of a software project, you may want |
| 957 | to simultaneously make a changelog to include in the release |
| 958 | announcement. |
| 959 | |
| 960 | Linus Torvalds, for example, makes new kernel releases by tagging them, |
| 961 | then running: |
| 962 | |
| 963 | ------------------------------------------------- |
| 964 | $ release-script 2.6.12 2.6.13-rc6 2.6.13-rc7 |
| 965 | ------------------------------------------------- |
| 966 | |
| 967 | where release-script is a shell script that looks like: |
| 968 | |
| 969 | ------------------------------------------------- |
| 970 | #!/bin/sh |
| 971 | stable="$1" |
| 972 | last="$2" |
| 973 | new="$3" |
| 974 | echo "# git tag v$new" |
| 975 | echo "git archive --prefix=linux-$new/ v$new | gzip -9 > ../linux-$new.tar.gz" |
| 976 | echo "git diff v$stable v$new | gzip -9 > ../patch-$new.gz" |
| 977 | echo "git log --no-merges v$new ^v$last > ../ChangeLog-$new" |
| 978 | echo "git shortlog --no-merges v$new ^v$last > ../ShortLog" |
| 979 | echo "git diff --stat --summary -M v$last v$new > ../diffstat-$new" |
| 980 | ------------------------------------------------- |
| 981 | |
| 982 | and then he just cut-and-pastes the output commands after verifying that |
| 983 | they look OK. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 984 | |
Junio C Hamano | 3b4609d | 2010-09-30 00:04:34 | [diff] [blame] | 985 | [[Finding-commits-With-given-Content]] |
Junio C Hamano | ed7f4f6 | 2007-05-20 09:09:09 | [diff] [blame] | 986 | Finding commits referencing a file with given content |
Junio C Hamano | 8b8b0f2 | 2007-08-26 22:10:26 | [diff] [blame] | 987 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Junio C Hamano | ed7f4f6 | 2007-05-20 09:09:09 | [diff] [blame] | 988 | |
| 989 | Somebody hands you a copy of a file, and asks which commits modified a |
| 990 | file such that it contained the given content either before or after the |
| 991 | commit. You can find out with this: |
| 992 | |
| 993 | ------------------------------------------------- |
Junio C Hamano | 764a667 | 2007-10-23 01:23:31 | [diff] [blame] | 994 | $ git log --raw --abbrev=40 --pretty=oneline | |
Junio C Hamano | ed7f4f6 | 2007-05-20 09:09:09 | [diff] [blame] | 995 | grep -B 1 `git hash-object filename` |
| 996 | ------------------------------------------------- |
| 997 | |
| 998 | Figuring out why this works is left as an exercise to the (advanced) |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 999 | student. The linkgit:git-log[1], linkgit:git-diff-tree[1], and |
| 1000 | linkgit:git-hash-object[1] man pages may prove helpful. |
Junio C Hamano | ed7f4f6 | 2007-05-20 09:09:09 | [diff] [blame] | 1001 | |
Junio C Hamano | ec87f52 | 2008-12-10 08:35:25 | [diff] [blame] | 1002 | [[Developing-With-git]] |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 1003 | Developing with Git |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1004 | =================== |
| 1005 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 1006 | [[telling-git-your-name]] |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 1007 | Telling Git your name |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1008 | --------------------- |
| 1009 | |
Junio C Hamano | 2da4ac4 | 2013-02-19 00:41:17 | [diff] [blame] | 1010 | Before creating any commits, you should introduce yourself to Git. |
| 1011 | The easiest way to do so is to use linkgit:git-config[1]: |
| 1012 | |
| 1013 | ------------------------------------------------ |
| 1014 | $ git config --global user.name 'Your Name Comes Here' |
| 1015 | $ git config --global user.email 'you@yourdomain.example.com' |
| 1016 | ------------------------------------------------ |
| 1017 | |
| 1018 | Which will add the following to a file named `.gitconfig` in your |
| 1019 | home directory: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1020 | |
| 1021 | ------------------------------------------------ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1022 | [user] |
| 1023 | name = Your Name Comes Here |
| 1024 | email = you@yourdomain.example.com |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1025 | ------------------------------------------------ |
| 1026 | |
Junio C Hamano | 2da4ac4 | 2013-02-19 00:41:17 | [diff] [blame] | 1027 | See the "CONFIGURATION FILE" section of linkgit:git-config[1] for |
| 1028 | details on the configuration file. The file is plain text, so you can |
| 1029 | also edit it with your favorite editor. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1030 | |
| 1031 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 1032 | [[creating-a-new-repository]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1033 | Creating a new repository |
| 1034 | ------------------------- |
| 1035 | |
| 1036 | Creating a new repository from scratch is very easy: |
| 1037 | |
| 1038 | ------------------------------------------------- |
| 1039 | $ mkdir project |
| 1040 | $ cd project |
| 1041 | $ git init |
| 1042 | ------------------------------------------------- |
| 1043 | |
| 1044 | If you have some initial content (say, a tarball): |
| 1045 | |
| 1046 | ------------------------------------------------- |
Junio C Hamano | 4fbdd44 | 2009-01-06 05:56:24 | [diff] [blame] | 1047 | $ tar xzvf project.tar.gz |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1048 | $ cd project |
| 1049 | $ git init |
| 1050 | $ git add . # include everything below ./ in the first commit: |
| 1051 | $ git commit |
| 1052 | ------------------------------------------------- |
| 1053 | |
| 1054 | [[how-to-make-a-commit]] |
Junio C Hamano | 12a3a23 | 2007-04-07 10:18:10 | [diff] [blame] | 1055 | How to make a commit |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1056 | -------------------- |
| 1057 | |
| 1058 | Creating a new commit takes three steps: |
| 1059 | |
| 1060 | 1. Making some changes to the working directory using your |
| 1061 | favorite editor. |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 1062 | 2. Telling Git about your changes. |
| 1063 | 3. Creating the commit using the content you told Git about |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1064 | in step 2. |
| 1065 | |
| 1066 | In practice, you can interleave and repeat steps 1 and 2 as many |
| 1067 | times as you want: in order to keep track of what you want committed |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 1068 | at step 3, Git maintains a snapshot of the tree's contents in a |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1069 | special staging area called "the index." |
| 1070 | |
| 1071 | At the beginning, the content of the index will be identical to |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 1072 | that of the HEAD. The command `git diff --cached`, which shows |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1073 | the difference between the HEAD and the index, should therefore |
| 1074 | produce no output at that point. |
| 1075 | |
| 1076 | Modifying the index is easy: |
| 1077 | |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 1078 | To update the index with the contents of a new or modified file, use |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1079 | |
| 1080 | ------------------------------------------------- |
| 1081 | $ git add path/to/file |
| 1082 | ------------------------------------------------- |
| 1083 | |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 1084 | To remove a file from the index and from the working tree, use |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1085 | |
| 1086 | ------------------------------------------------- |
| 1087 | $ git rm path/to/file |
| 1088 | ------------------------------------------------- |
| 1089 | |
| 1090 | After each step you can verify that |
| 1091 | |
| 1092 | ------------------------------------------------- |
| 1093 | $ git diff --cached |
| 1094 | ------------------------------------------------- |
| 1095 | |
| 1096 | always shows the difference between the HEAD and the index file--this |
| 1097 | is what you'd commit if you created the commit now--and that |
| 1098 | |
| 1099 | ------------------------------------------------- |
| 1100 | $ git diff |
| 1101 | ------------------------------------------------- |
| 1102 | |
| 1103 | shows the difference between the working tree and the index file. |
| 1104 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 1105 | Note that `git add` always adds just the current contents of a file |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1106 | to the index; further changes to the same file will be ignored unless |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 1107 | you run `git add` on the file again. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1108 | |
| 1109 | When you're ready, just run |
| 1110 | |
| 1111 | ------------------------------------------------- |
| 1112 | $ git commit |
| 1113 | ------------------------------------------------- |
| 1114 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 1115 | and Git will prompt you for a commit message and then create the new |
Junio C Hamano | ee1e428 | 2007-02-04 08:32:04 | [diff] [blame] | 1116 | commit. Check to make sure it looks like what you expected with |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1117 | |
| 1118 | ------------------------------------------------- |
| 1119 | $ git show |
| 1120 | ------------------------------------------------- |
| 1121 | |
| 1122 | As a special shortcut, |
Junio C Hamano | a77a513 | 2007-06-08 16:13:44 | [diff] [blame] | 1123 | |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1124 | ------------------------------------------------- |
| 1125 | $ git commit -a |
| 1126 | ------------------------------------------------- |
| 1127 | |
| 1128 | will update the index with any files that you've modified or removed |
| 1129 | and create a commit, all in one step. |
| 1130 | |
| 1131 | A number of commands are useful for keeping track of what you're |
| 1132 | about to commit: |
| 1133 | |
| 1134 | ------------------------------------------------- |
| 1135 | $ git diff --cached # difference between HEAD and the index; what |
Junio C Hamano | cc13f55 | 2007-07-24 08:59:43 | [diff] [blame] | 1136 | # would be committed if you ran "commit" now. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1137 | $ git diff # difference between the index file and your |
| 1138 | # working directory; changes that would not |
| 1139 | # be included if you ran "commit" now. |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 1140 | $ git diff HEAD # difference between HEAD and working tree; what |
| 1141 | # would be committed if you ran "commit -a" now. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1142 | $ git status # a brief per-file summary of the above. |
| 1143 | ------------------------------------------------- |
| 1144 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 1145 | You can also use linkgit:git-gui[1] to create commits, view changes in |
Junio C Hamano | 4cd1c0e | 2007-08-06 04:39:14 | [diff] [blame] | 1146 | the index and the working tree files, and individually select diff hunks |
| 1147 | for inclusion in the index (by right-clicking on the diff hunk and |
| 1148 | choosing "Stage Hunk For Commit"). |
| 1149 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 1150 | [[creating-good-commit-messages]] |
Junio C Hamano | 12a3a23 | 2007-04-07 10:18:10 | [diff] [blame] | 1151 | Creating good commit messages |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1152 | ----------------------------- |
| 1153 | |
| 1154 | Though not required, it's a good idea to begin the commit message |
| 1155 | with a single short (less than 50 character) line summarizing the |
| 1156 | change, followed by a blank line and then a more thorough |
Junio C Hamano | 281fd39 | 2012-09-17 23:57:41 | [diff] [blame] | 1157 | description. The text up to the first blank line in a commit |
| 1158 | message is treated as the commit title, and that title is used |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 1159 | throughout Git. For example, linkgit:git-format-patch[1] turns a |
Junio C Hamano | 281fd39 | 2012-09-17 23:57:41 | [diff] [blame] | 1160 | commit into email, and it uses the title on the Subject line and the |
| 1161 | rest of the commit in the body. |
| 1162 | |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1163 | |
Junio C Hamano | ed7f4f6 | 2007-05-20 09:09:09 | [diff] [blame] | 1164 | [[ignoring-files]] |
| 1165 | Ignoring files |
| 1166 | -------------- |
| 1167 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 1168 | A project will often generate files that you do 'not' want to track with Git. |
Junio C Hamano | ed7f4f6 | 2007-05-20 09:09:09 | [diff] [blame] | 1169 | This typically includes files generated by a build process or temporary |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 1170 | backup files made by your editor. Of course, 'not' tracking files with Git |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 1171 | is just a matter of 'not' calling `git add` on them. But it quickly becomes |
Junio C Hamano | ed7f4f6 | 2007-05-20 09:09:09 | [diff] [blame] | 1172 | annoying to have these untracked files lying around; e.g. they make |
Junio C Hamano | ea82cff | 2009-03-18 01:54:48 | [diff] [blame] | 1173 | `git add .` practically useless, and they keep showing up in the output of |
| 1174 | `git status`. |
Junio C Hamano | ed7f4f6 | 2007-05-20 09:09:09 | [diff] [blame] | 1175 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 1176 | You can tell Git to ignore certain files by creating a file called |
| 1177 | `.gitignore` in the top level of your working directory, with contents |
| 1178 | such as: |
Junio C Hamano | ed7f4f6 | 2007-05-20 09:09:09 | [diff] [blame] | 1179 | |
| 1180 | ------------------------------------------------- |
| 1181 | # Lines starting with '#' are considered comments. |
Junio C Hamano | 8b8b0f2 | 2007-08-26 22:10:26 | [diff] [blame] | 1182 | # Ignore any file named foo.txt. |
Junio C Hamano | ed7f4f6 | 2007-05-20 09:09:09 | [diff] [blame] | 1183 | foo.txt |
| 1184 | # Ignore (generated) html files, |
| 1185 | *.html |
| 1186 | # except foo.html which is maintained by hand. |
| 1187 | !foo.html |
| 1188 | # Ignore objects and archives. |
| 1189 | *.[oa] |
| 1190 | ------------------------------------------------- |
| 1191 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 1192 | See linkgit:gitignore[5] for a detailed explanation of the syntax. You can |
Junio C Hamano | 8b8b0f2 | 2007-08-26 22:10:26 | [diff] [blame] | 1193 | also place .gitignore files in other directories in your working tree, and they |
| 1194 | will apply to those directories and their subdirectories. The `.gitignore` |
| 1195 | files can be added to your repository like any other files (just run `git add |
| 1196 | .gitignore` and `git commit`, as usual), which is convenient when the exclude |
| 1197 | patterns (such as patterns matching build output files) would also make sense |
| 1198 | for other users who clone your repository. |
Junio C Hamano | ed7f4f6 | 2007-05-20 09:09:09 | [diff] [blame] | 1199 | |
Junio C Hamano | 8b8b0f2 | 2007-08-26 22:10:26 | [diff] [blame] | 1200 | If you wish the exclude patterns to affect only certain repositories |
| 1201 | (instead of every repository for a given project), you may instead put |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 1202 | them in a file in your repository named `.git/info/exclude`, or in any |
Junio C Hamano | 322c624 | 2015-03-23 21:32:46 | [diff] [blame] | 1203 | file specified by the `core.excludesFile` configuration variable. |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 1204 | Some Git commands can also take exclude patterns directly on the |
| 1205 | command line. See linkgit:gitignore[5] for the details. |
Junio C Hamano | ed7f4f6 | 2007-05-20 09:09:09 | [diff] [blame] | 1206 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 1207 | [[how-to-merge]] |
Junio C Hamano | 12a3a23 | 2007-04-07 10:18:10 | [diff] [blame] | 1208 | How to merge |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1209 | ------------ |
| 1210 | |
| 1211 | You can rejoin two diverging branches of development using |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 1212 | linkgit:git-merge[1]: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1213 | |
| 1214 | ------------------------------------------------- |
| 1215 | $ git merge branchname |
| 1216 | ------------------------------------------------- |
| 1217 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 1218 | merges the development in the branch `branchname` into the current |
Junio C Hamano | 5706e0b | 2009-11-24 10:54:16 | [diff] [blame] | 1219 | branch. |
| 1220 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 1221 | A merge is made by combining the changes made in `branchname` and the |
Junio C Hamano | 5706e0b | 2009-11-24 10:54:16 | [diff] [blame] | 1222 | changes made up to the latest commit in your current branch since |
| 1223 | their histories forked. The work tree is overwritten by the result of |
| 1224 | the merge when this combining is done cleanly, or overwritten by a |
| 1225 | half-merged results when this combining results in conflicts. |
| 1226 | Therefore, if you have uncommitted changes touching the same files as |
| 1227 | the ones impacted by the merge, Git will refuse to proceed. Most of |
| 1228 | the time, you will want to commit your changes before you can merge, |
| 1229 | and if you don't, then linkgit:git-stash[1] can take these changes |
| 1230 | away while you're doing the merge, and reapply them afterwards. |
| 1231 | |
Junio C Hamano | 167b138 | 2010-01-31 23:04:31 | [diff] [blame] | 1232 | If the changes are independent enough, Git will automatically complete |
Junio C Hamano | 5706e0b | 2009-11-24 10:54:16 | [diff] [blame] | 1233 | the merge and commit the result (or reuse an existing commit in case |
| 1234 | of <<fast-forwards,fast-forward>>, see below). On the other hand, |
| 1235 | if there are conflicts--for example, if the same file is |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1236 | modified in two different ways in the remote branch and the local |
| 1237 | branch--then you are warned; the output may look something like this: |
| 1238 | |
| 1239 | ------------------------------------------------- |
Junio C Hamano | c51fede | 2007-03-12 07:29:20 | [diff] [blame] | 1240 | $ git merge next |
| 1241 | 100% (4/4) done |
| 1242 | Auto-merged file.txt |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1243 | CONFLICT (content): Merge conflict in file.txt |
| 1244 | Automatic merge failed; fix conflicts and then commit the result. |
| 1245 | ------------------------------------------------- |
| 1246 | |
| 1247 | Conflict markers are left in the problematic files, and after |
| 1248 | you resolve the conflicts manually, you can update the index |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 1249 | with the contents and run Git commit, as you normally would when |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1250 | creating a new file. |
| 1251 | |
| 1252 | If you examine the resulting commit using gitk, you will see that it |
| 1253 | has two parents, one pointing to the top of the current branch, and |
| 1254 | one to the top of the other branch. |
| 1255 | |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1256 | [[resolving-a-merge]] |
| 1257 | Resolving a merge |
| 1258 | ----------------- |
| 1259 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 1260 | When a merge isn't resolved automatically, Git leaves the index and |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1261 | the working tree in a special state that gives you all the |
| 1262 | information you need to help resolve the merge. |
| 1263 | |
| 1264 | Files with conflicts are marked specially in the index, so until you |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 1265 | resolve the problem and update the index, linkgit:git-commit[1] will |
Junio C Hamano | aa83a7d | 2007-03-05 02:37:29 | [diff] [blame] | 1266 | fail: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1267 | |
| 1268 | ------------------------------------------------- |
| 1269 | $ git commit |
| 1270 | file.txt: needs merge |
| 1271 | ------------------------------------------------- |
| 1272 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 1273 | Also, linkgit:git-status[1] will list those files as "unmerged", and the |
Junio C Hamano | aa83a7d | 2007-03-05 02:37:29 | [diff] [blame] | 1274 | files with conflicts will have conflict markers added, like this: |
| 1275 | |
| 1276 | ------------------------------------------------- |
| 1277 | <<<<<<< HEAD:file.txt |
| 1278 | Hello world |
| 1279 | ======= |
| 1280 | Goodbye |
| 1281 | >>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt |
| 1282 | ------------------------------------------------- |
| 1283 | |
| 1284 | All you need to do is edit the files to resolve the conflicts, and then |
| 1285 | |
| 1286 | ------------------------------------------------- |
| 1287 | $ git add file.txt |
| 1288 | $ git commit |
| 1289 | ------------------------------------------------- |
| 1290 | |
| 1291 | Note that the commit message will already be filled in for you with |
| 1292 | some information about the merge. Normally you can just use this |
| 1293 | default message unchanged, but you may add additional commentary of |
| 1294 | your own if desired. |
| 1295 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 1296 | The above is all you need to know to resolve a simple merge. But Git |
Junio C Hamano | aa83a7d | 2007-03-05 02:37:29 | [diff] [blame] | 1297 | also provides more information to help resolve conflicts: |
| 1298 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 1299 | [[conflict-resolution]] |
Junio C Hamano | aa83a7d | 2007-03-05 02:37:29 | [diff] [blame] | 1300 | Getting conflict-resolution help during a merge |
| 1301 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1302 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 1303 | All of the changes that Git was able to merge automatically are |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 1304 | already added to the index file, so linkgit:git-diff[1] shows only |
Junio C Hamano | aa83a7d | 2007-03-05 02:37:29 | [diff] [blame] | 1305 | the conflicts. It uses an unusual syntax: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1306 | |
| 1307 | ------------------------------------------------- |
| 1308 | $ git diff |
| 1309 | diff --cc file.txt |
| 1310 | index 802992c,2b60207..0000000 |
| 1311 | --- a/file.txt |
| 1312 | +++ b/file.txt |
| 1313 | @@@ -1,1 -1,1 +1,5 @@@ |
| 1314 | ++<<<<<<< HEAD:file.txt |
| 1315 | +Hello world |
| 1316 | ++======= |
| 1317 | + Goodbye |
| 1318 | ++>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt |
| 1319 | ------------------------------------------------- |
| 1320 | |
Junio C Hamano | cc13f55 | 2007-07-24 08:59:43 | [diff] [blame] | 1321 | Recall that the commit which will be committed after we resolve this |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1322 | conflict will have two parents instead of the usual one: one parent |
| 1323 | will be HEAD, the tip of the current branch; the other will be the |
| 1324 | tip of the other branch, which is stored temporarily in MERGE_HEAD. |
| 1325 | |
Junio C Hamano | aa83a7d | 2007-03-05 02:37:29 | [diff] [blame] | 1326 | During the merge, the index holds three versions of each file. Each of |
| 1327 | these three "file stages" represents a different version of the file: |
| 1328 | |
| 1329 | ------------------------------------------------- |
| 1330 | $ git show :1:file.txt # the file in a common ancestor of both branches |
Junio C Hamano | 6fb124c | 2008-06-13 10:04:01 | [diff] [blame] | 1331 | $ git show :2:file.txt # the version from HEAD. |
| 1332 | $ git show :3:file.txt # the version from MERGE_HEAD. |
Junio C Hamano | aa83a7d | 2007-03-05 02:37:29 | [diff] [blame] | 1333 | ------------------------------------------------- |
| 1334 | |
Junio C Hamano | 6fb124c | 2008-06-13 10:04:01 | [diff] [blame] | 1335 | When you ask linkgit:git-diff[1] to show the conflicts, it runs a |
| 1336 | three-way diff between the conflicted merge results in the work tree with |
| 1337 | stages 2 and 3 to show only hunks whose contents come from both sides, |
| 1338 | mixed (in other words, when a hunk's merge results come only from stage 2, |
| 1339 | that part is not conflicting and is not shown. Same for stage 3). |
Junio C Hamano | aa83a7d | 2007-03-05 02:37:29 | [diff] [blame] | 1340 | |
| 1341 | The diff above shows the differences between the working-tree version of |
| 1342 | file.txt and the stage 2 and stage 3 versions. So instead of preceding |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 1343 | each line by a single `+` or `-`, it now uses two columns: the first |
Junio C Hamano | aa83a7d | 2007-03-05 02:37:29 | [diff] [blame] | 1344 | column is used for differences between the first parent and the working |
| 1345 | directory copy, and the second for differences between the second parent |
| 1346 | and the working directory copy. (See the "COMBINED DIFF FORMAT" section |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 1347 | of linkgit:git-diff-files[1] for a details of the format.) |
Junio C Hamano | aa83a7d | 2007-03-05 02:37:29 | [diff] [blame] | 1348 | |
| 1349 | After resolving the conflict in the obvious way (but before updating the |
| 1350 | index), the diff will look like: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1351 | |
| 1352 | ------------------------------------------------- |
| 1353 | $ git diff |
| 1354 | diff --cc file.txt |
| 1355 | index 802992c,2b60207..0000000 |
| 1356 | --- a/file.txt |
| 1357 | +++ b/file.txt |
| 1358 | @@@ -1,1 -1,1 +1,1 @@@ |
| 1359 | - Hello world |
| 1360 | -Goodbye |
| 1361 | ++Goodbye world |
| 1362 | ------------------------------------------------- |
| 1363 | |
| 1364 | This shows that our resolved version deleted "Hello world" from the |
| 1365 | first parent, deleted "Goodbye" from the second parent, and added |
| 1366 | "Goodbye world", which was previously absent from both. |
| 1367 | |
Junio C Hamano | aa83a7d | 2007-03-05 02:37:29 | [diff] [blame] | 1368 | Some special diff options allow diffing the working directory against |
| 1369 | any of these stages: |
| 1370 | |
| 1371 | ------------------------------------------------- |
| 1372 | $ git diff -1 file.txt # diff against stage 1 |
| 1373 | $ git diff --base file.txt # same as the above |
| 1374 | $ git diff -2 file.txt # diff against stage 2 |
| 1375 | $ git diff --ours file.txt # same as the above |
| 1376 | $ git diff -3 file.txt # diff against stage 3 |
| 1377 | $ git diff --theirs file.txt # same as the above. |
| 1378 | ------------------------------------------------- |
| 1379 | |
Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1380 | The linkgit:git-log[1] and linkgit:gitk[1] commands also provide special help |
Junio C Hamano | aa83a7d | 2007-03-05 02:37:29 | [diff] [blame] | 1381 | for merges: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1382 | |
| 1383 | ------------------------------------------------- |
| 1384 | $ git log --merge |
Junio C Hamano | aa83a7d | 2007-03-05 02:37:29 | [diff] [blame] | 1385 | $ gitk --merge |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1386 | ------------------------------------------------- |
| 1387 | |
Junio C Hamano | aa83a7d | 2007-03-05 02:37:29 | [diff] [blame] | 1388 | These will display all commits which exist only on HEAD or on |
| 1389 | MERGE_HEAD, and which touch an unmerged file. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1390 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 1391 | You may also use linkgit:git-mergetool[1], which lets you merge the |
Junio C Hamano | 4fbdd44 | 2009-01-06 05:56:24 | [diff] [blame] | 1392 | unmerged files using external tools such as Emacs or kdiff3. |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 1393 | |
Junio C Hamano | aa83a7d | 2007-03-05 02:37:29 | [diff] [blame] | 1394 | Each time you resolve the conflicts in a file and update the index: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1395 | |
| 1396 | ------------------------------------------------- |
| 1397 | $ git add file.txt |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1398 | ------------------------------------------------- |
| 1399 | |
Junio C Hamano | aa83a7d | 2007-03-05 02:37:29 | [diff] [blame] | 1400 | the different stages of that file will be "collapsed", after which |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 1401 | `git diff` will (by default) no longer show diffs for that file. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1402 | |
| 1403 | [[undoing-a-merge]] |
Junio C Hamano | 12a3a23 | 2007-04-07 10:18:10 | [diff] [blame] | 1404 | Undoing a merge |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1405 | --------------- |
| 1406 | |
| 1407 | If you get stuck and decide to just give up and throw the whole mess |
| 1408 | away, you can always return to the pre-merge state with |
| 1409 | |
| 1410 | ------------------------------------------------- |
| 1411 | $ git reset --hard HEAD |
| 1412 | ------------------------------------------------- |
| 1413 | |
Junio C Hamano | cc13f55 | 2007-07-24 08:59:43 | [diff] [blame] | 1414 | Or, if you've already committed the merge that you want to throw away, |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1415 | |
| 1416 | ------------------------------------------------- |
Junio C Hamano | aa83a7d | 2007-03-05 02:37:29 | [diff] [blame] | 1417 | $ git reset --hard ORIG_HEAD |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1418 | ------------------------------------------------- |
| 1419 | |
| 1420 | However, this last command can be dangerous in some cases--never |
| 1421 | throw away a commit you have already committed if that commit may |
| 1422 | itself have been merged into another branch, as doing so may confuse |
| 1423 | further merges. |
| 1424 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 1425 | [[fast-forwards]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1426 | Fast-forward merges |
| 1427 | ------------------- |
| 1428 | |
| 1429 | There is one special case not mentioned above, which is treated |
| 1430 | differently. Normally, a merge results in a merge commit, with two |
| 1431 | parents, one pointing at each of the two lines of development that |
| 1432 | were merged. |
| 1433 | |
Junio C Hamano | 448d132 | 2015-10-30 21:57:54 | [diff] [blame^] | 1434 | However, if the current branch is an ancestor of the other--so every commit |
| 1435 | present in the current branch is already contained in the other branch--then Git |
| 1436 | just performs a "fast-forward"; the head of the current branch is moved forward |
| 1437 | to point at the head of the merged-in branch, without any new commits being |
| 1438 | created. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1439 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 1440 | [[fixing-mistakes]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1441 | Fixing mistakes |
| 1442 | --------------- |
| 1443 | |
| 1444 | If you've messed up the working tree, but haven't yet committed your |
| 1445 | mistake, you can return the entire working tree to the last committed |
| 1446 | state with |
| 1447 | |
| 1448 | ------------------------------------------------- |
| 1449 | $ git reset --hard HEAD |
| 1450 | ------------------------------------------------- |
| 1451 | |
| 1452 | If you make a commit that you later wish you hadn't, there are two |
| 1453 | fundamentally different ways to fix the problem: |
| 1454 | |
| 1455 | 1. You can create a new commit that undoes whatever was done |
Junio C Hamano | 8c5802d | 2007-11-15 00:13:36 | [diff] [blame] | 1456 | by the old commit. This is the correct thing if your |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1457 | mistake has already been made public. |
| 1458 | |
| 1459 | 2. You can go back and modify the old commit. You should |
| 1460 | never do this if you have already made the history public; |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 1461 | Git does not normally expect the "history" of a project to |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1462 | change, and cannot correctly perform repeated merges from |
| 1463 | a branch that has had its history changed. |
| 1464 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 1465 | [[reverting-a-commit]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1466 | Fixing a mistake with a new commit |
| 1467 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1468 | |
| 1469 | Creating a new commit that reverts an earlier change is very easy; |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 1470 | just pass the linkgit:git-revert[1] command a reference to the bad |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1471 | commit; for example, to revert the most recent commit: |
| 1472 | |
| 1473 | ------------------------------------------------- |
| 1474 | $ git revert HEAD |
| 1475 | ------------------------------------------------- |
| 1476 | |
| 1477 | This will create a new commit which undoes the change in HEAD. You |
| 1478 | will be given a chance to edit the commit message for the new commit. |
| 1479 | |
| 1480 | You can also revert an earlier change, for example, the next-to-last: |
| 1481 | |
| 1482 | ------------------------------------------------- |
| 1483 | $ git revert HEAD^ |
| 1484 | ------------------------------------------------- |
| 1485 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 1486 | In this case Git will attempt to undo the old change while leaving |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1487 | intact any changes made since then. If more recent changes overlap |
| 1488 | with the changes to be reverted, then you will be asked to fix |
| 1489 | conflicts manually, just as in the case of <<resolving-a-merge, |
| 1490 | resolving a merge>>. |
| 1491 | |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 1492 | [[fixing-a-mistake-by-rewriting-history]] |
| 1493 | Fixing a mistake by rewriting history |
Junio C Hamano | ee61580 | 2015-10-29 21:45:26 | [diff] [blame] | 1494 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1495 | |
| 1496 | If the problematic commit is the most recent commit, and you have not |
| 1497 | yet made that commit public, then you may just |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 1498 | <<undoing-a-merge,destroy it using `git reset`>>. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1499 | |
| 1500 | Alternatively, you |
| 1501 | can edit the working directory and update the index to fix your |
| 1502 | mistake, just as if you were going to <<how-to-make-a-commit,create a |
| 1503 | new commit>>, then run |
| 1504 | |
| 1505 | ------------------------------------------------- |
| 1506 | $ git commit --amend |
| 1507 | ------------------------------------------------- |
| 1508 | |
| 1509 | which will replace the old commit by a new commit incorporating your |
| 1510 | changes, giving you a chance to edit the old commit message first. |
| 1511 | |
| 1512 | Again, you should never do this to a commit that may already have |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 1513 | been merged into another branch; use linkgit:git-revert[1] instead in |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1514 | that case. |
| 1515 | |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 1516 | It is also possible to replace commits further back in the history, but |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1517 | this is an advanced topic to be left for |
| 1518 | <<cleaning-up-history,another chapter>>. |
| 1519 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 1520 | [[checkout-of-path]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1521 | Checking out an old version of a file |
| 1522 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1523 | |
| 1524 | In the process of undoing a previous bad change, you may find it |
| 1525 | useful to check out an older version of a particular file using |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 1526 | linkgit:git-checkout[1]. We've used `git checkout` before to switch |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1527 | branches, but it has quite different behavior if it is given a path |
| 1528 | name: the command |
| 1529 | |
| 1530 | ------------------------------------------------- |
| 1531 | $ git checkout HEAD^ path/to/file |
| 1532 | ------------------------------------------------- |
| 1533 | |
| 1534 | replaces path/to/file by the contents it had in the commit HEAD^, and |
| 1535 | also updates the index to match. It does not change branches. |
| 1536 | |
| 1537 | If you just want to look at an old version of the file, without |
| 1538 | modifying the working directory, you can do that with |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 1539 | linkgit:git-show[1]: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1540 | |
| 1541 | ------------------------------------------------- |
Junio C Hamano | c51fede | 2007-03-12 07:29:20 | [diff] [blame] | 1542 | $ git show HEAD^:path/to/file |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1543 | ------------------------------------------------- |
| 1544 | |
| 1545 | which will display the given version of the file. |
| 1546 | |
Junio C Hamano | 4cd1c0e | 2007-08-06 04:39:14 | [diff] [blame] | 1547 | [[interrupted-work]] |
| 1548 | Temporarily setting aside work in progress |
| 1549 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1550 | |
| 1551 | While you are in the middle of working on something complicated, you |
| 1552 | find an unrelated but obvious and trivial bug. You would like to fix it |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 1553 | before continuing. You can use linkgit:git-stash[1] to save the current |
Junio C Hamano | 4cd1c0e | 2007-08-06 04:39:14 | [diff] [blame] | 1554 | state of your work, and after fixing the bug (or, optionally after doing |
| 1555 | so on a different branch and then coming back), unstash the |
| 1556 | work-in-progress changes. |
| 1557 | |
| 1558 | ------------------------------------------------ |
Junio C Hamano | 7850245 | 2009-02-04 16:53:50 | [diff] [blame] | 1559 | $ git stash save "work in progress for foo feature" |
Junio C Hamano | 4cd1c0e | 2007-08-06 04:39:14 | [diff] [blame] | 1560 | ------------------------------------------------ |
| 1561 | |
| 1562 | This command will save your changes away to the `stash`, and |
| 1563 | reset your working tree and the index to match the tip of your |
| 1564 | current branch. Then you can make your fix as usual. |
| 1565 | |
| 1566 | ------------------------------------------------ |
| 1567 | ... edit and test ... |
| 1568 | $ git commit -a -m "blorpl: typofix" |
| 1569 | ------------------------------------------------ |
| 1570 | |
| 1571 | After that, you can go back to what you were working on with |
Junio C Hamano | 7d3275e | 2009-05-31 21:53:30 | [diff] [blame] | 1572 | `git stash pop`: |
Junio C Hamano | 4cd1c0e | 2007-08-06 04:39:14 | [diff] [blame] | 1573 | |
| 1574 | ------------------------------------------------ |
Junio C Hamano | 7d3275e | 2009-05-31 21:53:30 | [diff] [blame] | 1575 | $ git stash pop |
Junio C Hamano | 4cd1c0e | 2007-08-06 04:39:14 | [diff] [blame] | 1576 | ------------------------------------------------ |
| 1577 | |
| 1578 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 1579 | [[ensuring-good-performance]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1580 | Ensuring good performance |
| 1581 | ------------------------- |
| 1582 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 1583 | On large repositories, Git depends on compression to keep the history |
Junio C Hamano | 8c5696d | 2013-02-11 05:35:00 | [diff] [blame] | 1584 | information from taking up too much space on disk or in memory. Some |
| 1585 | Git commands may automatically run linkgit:git-gc[1], so you don't |
| 1586 | have to worry about running it manually. However, compressing a large |
| 1587 | repository may take a while, so you may want to call `gc` explicitly |
| 1588 | to avoid automatic compression kicking in when it is not convenient. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1589 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 1590 | |
| 1591 | [[ensuring-reliability]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1592 | Ensuring reliability |
| 1593 | -------------------- |
| 1594 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 1595 | [[checking-for-corruption]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1596 | Checking the repository for corruption |
| 1597 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1598 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 1599 | The linkgit:git-fsck[1] command runs a number of self-consistency checks |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1600 | on the repository, and reports on any problems. This may take some |
Junio C Hamano | 81d540a | 2012-03-02 19:52:47 | [diff] [blame] | 1601 | time. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1602 | |
| 1603 | ------------------------------------------------- |
| 1604 | $ git fsck |
| 1605 | dangling commit 7281251ddd2a61e38657c827739c57015671a6b3 |
| 1606 | dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a63 |
| 1607 | dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b5 |
| 1608 | dangling blob 218761f9d90712d37a9c5e36f406f92202db07eb |
| 1609 | dangling commit bf093535a34a4d35731aa2bd90fe6b176302f14f |
| 1610 | dangling commit 8e4bec7f2ddaa268bef999853c25755452100f8e |
| 1611 | dangling tree d50bb86186bf27b681d25af89d3b5b68382e4085 |
| 1612 | dangling tree b24c2473f1fd3d91352a624795be026d64c8841f |
| 1613 | ... |
| 1614 | ------------------------------------------------- |
| 1615 | |
Junio C Hamano | 81d540a | 2012-03-02 19:52:47 | [diff] [blame] | 1616 | You will see informational messages on dangling objects. They are objects |
| 1617 | that still exist in the repository but are no longer referenced by any of |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 1618 | your branches, and can (and will) be removed after a while with `gc`. |
Junio C Hamano | 010705a | 2012-06-19 23:37:26 | [diff] [blame] | 1619 | You can run `git fsck --no-dangling` to suppress these messages, and still |
Junio C Hamano | 81d540a | 2012-03-02 19:52:47 | [diff] [blame] | 1620 | view real errors. |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 1621 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 1622 | [[recovering-lost-changes]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1623 | Recovering lost changes |
| 1624 | ~~~~~~~~~~~~~~~~~~~~~~~ |
| 1625 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 1626 | [[reflogs]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1627 | Reflogs |
| 1628 | ^^^^^^^ |
| 1629 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 1630 | Say you modify a branch with <<fixing-mistakes,`git reset --hard`>>, |
| 1631 | and then realize that the branch was the only reference you had to |
| 1632 | that point in history. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1633 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 1634 | Fortunately, Git also keeps a log, called a "reflog", of all the |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1635 | previous values of each branch. So in this case you can still find the |
Junio C Hamano | a77a513 | 2007-06-08 16:13:44 | [diff] [blame] | 1636 | old history using, for example, |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1637 | |
| 1638 | ------------------------------------------------- |
| 1639 | $ git log master@{1} |
| 1640 | ------------------------------------------------- |
| 1641 | |
Junio C Hamano | 63777e2 | 2007-11-17 20:52:16 | [diff] [blame] | 1642 | This lists the commits reachable from the previous version of the |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 1643 | `master` branch head. This syntax can be used with any Git command |
| 1644 | that accepts a commit, not just with `git log`. Some other examples: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1645 | |
| 1646 | ------------------------------------------------- |
| 1647 | $ git show master@{2} # See where the branch pointed 2, |
| 1648 | $ git show master@{3} # 3, ... changes ago. |
| 1649 | $ gitk master@{yesterday} # See where it pointed yesterday, |
| 1650 | $ gitk master@{"1 week ago"} # ... or last week |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 1651 | $ git log --walk-reflogs master # show reflog entries for master |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1652 | ------------------------------------------------- |
| 1653 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 1654 | A separate reflog is kept for the HEAD, so |
| 1655 | |
| 1656 | ------------------------------------------------- |
| 1657 | $ git show HEAD@{"1 week ago"} |
| 1658 | ------------------------------------------------- |
| 1659 | |
| 1660 | will show what HEAD pointed to one week ago, not what the current branch |
| 1661 | pointed to one week ago. This allows you to see the history of what |
| 1662 | you've checked out. |
| 1663 | |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1664 | The reflogs are kept by default for 30 days, after which they may be |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 1665 | pruned. See linkgit:git-reflog[1] and linkgit:git-gc[1] to learn |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1666 | how to control this pruning, and see the "SPECIFYING REVISIONS" |
Junio C Hamano | c27b733 | 2010-10-14 04:37:28 | [diff] [blame] | 1667 | section of linkgit:gitrevisions[7] for details. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1668 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 1669 | Note that the reflog history is very different from normal Git history. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1670 | While normal history is shared by every repository that works on the |
| 1671 | same project, the reflog history is not shared: it tells you only about |
| 1672 | how the branches in your local repository have changed over time. |
| 1673 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 1674 | [[dangling-object-recovery]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1675 | Examining dangling objects |
| 1676 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 1677 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 1678 | In some situations the reflog may not be able to save you. For example, |
| 1679 | suppose you delete a branch, then realize you need the history it |
| 1680 | contained. The reflog is also deleted; however, if you have not yet |
| 1681 | pruned the repository, then you may still be able to find the lost |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 1682 | commits in the dangling objects that `git fsck` reports. See |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 1683 | <<dangling-objects>> for the details. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1684 | |
| 1685 | ------------------------------------------------- |
| 1686 | $ git fsck |
| 1687 | dangling commit 7281251ddd2a61e38657c827739c57015671a6b3 |
| 1688 | dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a63 |
| 1689 | dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b5 |
| 1690 | ... |
| 1691 | ------------------------------------------------- |
| 1692 | |
Junio C Hamano | 39381a7 | 2007-02-02 07:35:15 | [diff] [blame] | 1693 | You can examine |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1694 | one of those dangling commits with, for example, |
| 1695 | |
| 1696 | ------------------------------------------------ |
| 1697 | $ gitk 7281251ddd --not --all |
| 1698 | ------------------------------------------------ |
| 1699 | |
| 1700 | which does what it sounds like: it says that you want to see the commit |
| 1701 | history that is described by the dangling commit(s), but not the |
| 1702 | history that is described by all your existing branches and tags. Thus |
| 1703 | you get exactly the history reachable from that commit that is lost. |
| 1704 | (And notice that it might not be just one commit: we only report the |
| 1705 | "tip of the line" as being dangling, but there might be a whole deep |
Junio C Hamano | db911ee | 2007-02-28 08:13:52 | [diff] [blame] | 1706 | and complex commit history that was dropped.) |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1707 | |
| 1708 | If you decide you want the history back, you can always create a new |
| 1709 | reference pointing to it, for example, a new branch: |
| 1710 | |
| 1711 | ------------------------------------------------ |
Junio C Hamano | a77a513 | 2007-06-08 16:13:44 | [diff] [blame] | 1712 | $ git branch recovered-branch 7281251ddd |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1713 | ------------------------------------------------ |
| 1714 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 1715 | Other types of dangling objects (blobs and trees) are also possible, and |
| 1716 | dangling objects can arise in other situations. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1717 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 1718 | |
| 1719 | [[sharing-development]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1720 | Sharing development with others |
| 1721 | =============================== |
| 1722 | |
Junio C Hamano | ec87f52 | 2008-12-10 08:35:25 | [diff] [blame] | 1723 | [[getting-updates-With-git-pull]] |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 1724 | Getting updates with git pull |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1725 | ----------------------------- |
| 1726 | |
Junio C Hamano | 5706e0b | 2009-11-24 10:54:16 | [diff] [blame] | 1727 | After you clone a repository and commit a few changes of your own, you |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1728 | may wish to check the original repository for updates and merge them |
| 1729 | into your own work. |
| 1730 | |
Junio C Hamano | ec87f52 | 2008-12-10 08:35:25 | [diff] [blame] | 1731 | We have already seen <<Updating-a-repository-With-git-fetch,how to |
Junio C Hamano | 97bcb48 | 2010-11-25 03:16:07 | [diff] [blame] | 1732 | keep remote-tracking branches up to date>> with linkgit:git-fetch[1], |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1733 | and how to merge two branches. So you can merge in changes from the |
| 1734 | original repository's master branch with: |
| 1735 | |
| 1736 | ------------------------------------------------- |
| 1737 | $ git fetch |
| 1738 | $ git merge origin/master |
| 1739 | ------------------------------------------------- |
| 1740 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 1741 | However, the linkgit:git-pull[1] command provides a way to do this in |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1742 | one step: |
| 1743 | |
| 1744 | ------------------------------------------------- |
| 1745 | $ git pull origin master |
| 1746 | ------------------------------------------------- |
| 1747 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 1748 | In fact, if you have `master` checked out, then this branch has been |
| 1749 | configured by `git clone` to get changes from the HEAD branch of the |
Junio C Hamano | 97bcb48 | 2010-11-25 03:16:07 | [diff] [blame] | 1750 | origin repository. So often you can |
Junio C Hamano | 4cd1c0e | 2007-08-06 04:39:14 | [diff] [blame] | 1751 | accomplish the above with just a simple |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1752 | |
| 1753 | ------------------------------------------------- |
| 1754 | $ git pull |
| 1755 | ------------------------------------------------- |
| 1756 | |
Junio C Hamano | 97bcb48 | 2010-11-25 03:16:07 | [diff] [blame] | 1757 | This command will fetch changes from the remote branches to your |
| 1758 | remote-tracking branches `origin/*`, and merge the default branch into |
| 1759 | the current branch. |
| 1760 | |
| 1761 | More generally, a branch that is created from a remote-tracking branch |
| 1762 | will pull |
Junio C Hamano | 4cd1c0e | 2007-08-06 04:39:14 | [diff] [blame] | 1763 | by default from that branch. See the descriptions of the |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 1764 | `branch.<name>.remote` and `branch.<name>.merge` options in |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 1765 | linkgit:git-config[1], and the discussion of the `--track` option in |
| 1766 | linkgit:git-checkout[1], to learn how to control these defaults. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1767 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 1768 | In addition to saving you keystrokes, `git pull` also helps you by |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1769 | producing a default commit message documenting the branch and |
| 1770 | repository that you pulled from. |
| 1771 | |
| 1772 | (But note that no such commit will be created in the case of a |
Junio C Hamano | 3f680f3 | 2009-11-16 02:10:54 | [diff] [blame] | 1773 | <<fast-forwards,fast-forward>>; instead, your branch will just be |
Junio C Hamano | db911ee | 2007-02-28 08:13:52 | [diff] [blame] | 1774 | updated to point to the latest commit from the upstream branch.) |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1775 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 1776 | The `git pull` command can also be given `.` as the "remote" repository, |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1777 | in which case it just merges in a branch from the current repository; so |
| 1778 | the commands |
| 1779 | |
| 1780 | ------------------------------------------------- |
| 1781 | $ git pull . branch |
| 1782 | $ git merge branch |
| 1783 | ------------------------------------------------- |
| 1784 | |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 1785 | are roughly equivalent. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1786 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 1787 | [[submitting-patches]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1788 | Submitting patches to a project |
| 1789 | ------------------------------- |
| 1790 | |
| 1791 | If you just have a few changes, the simplest way to submit them may |
| 1792 | just be to send them as patches in email: |
| 1793 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 1794 | First, use linkgit:git-format-patch[1]; for example: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1795 | |
| 1796 | ------------------------------------------------- |
| 1797 | $ git format-patch origin |
| 1798 | ------------------------------------------------- |
| 1799 | |
| 1800 | will produce a numbered series of files in the current directory, one |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 1801 | for each patch in the current branch but not in `origin/HEAD`. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1802 | |
Junio C Hamano | 4eb2b9c | 2012-11-15 21:12:29 | [diff] [blame] | 1803 | `git format-patch` can include an initial "cover letter". You can insert |
| 1804 | commentary on individual patches after the three dash line which |
| 1805 | `format-patch` places after the commit message but before the patch |
| 1806 | itself. If you use `git notes` to track your cover letter material, |
| 1807 | `git format-patch --notes` will include the commit's notes in a similar |
| 1808 | manner. |
| 1809 | |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1810 | You can then import these into your mail client and send them by |
| 1811 | hand. However, if you have a lot to send at once, you may prefer to |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 1812 | use the linkgit:git-send-email[1] script to automate the process. |
Junio C Hamano | c8c398a | 2014-06-16 21:14:05 | [diff] [blame] | 1813 | Consult the mailing list for your project first to determine |
| 1814 | their requirements for submitting patches. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1815 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 1816 | [[importing-patches]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1817 | Importing patches to a project |
| 1818 | ------------------------------ |
| 1819 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 1820 | Git also provides a tool called linkgit:git-am[1] (am stands for |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1821 | "apply mailbox"), for importing such an emailed series of patches. |
| 1822 | Just save all of the patch-containing messages, in order, into a |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 1823 | single mailbox file, say `patches.mbox`, then run |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1824 | |
| 1825 | ------------------------------------------------- |
| 1826 | $ git am -3 patches.mbox |
| 1827 | ------------------------------------------------- |
| 1828 | |
| 1829 | Git will apply each patch in order; if any conflicts are found, it |
| 1830 | will stop, and you can fix the conflicts as described in |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 1831 | "<<resolving-a-merge,Resolving a merge>>". (The `-3` option tells |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 1832 | Git to perform a merge; if you would prefer it just to abort and |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1833 | leave your tree and index untouched, you may omit that option.) |
| 1834 | |
| 1835 | Once the index is updated with the results of the conflict |
| 1836 | resolution, instead of creating a new commit, just run |
| 1837 | |
| 1838 | ------------------------------------------------- |
Junio C Hamano | a195230 | 2013-07-01 21:31:18 | [diff] [blame] | 1839 | $ git am --continue |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1840 | ------------------------------------------------- |
| 1841 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 1842 | and Git will create the commit for you and continue applying the |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1843 | remaining patches from the mailbox. |
| 1844 | |
| 1845 | The final result will be a series of commits, one for each patch in |
| 1846 | the original mailbox, with authorship and commit log message each |
| 1847 | taken from the message containing each patch. |
| 1848 | |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 1849 | [[public-repositories]] |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 1850 | Public Git repositories |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 1851 | ----------------------- |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1852 | |
Junio C Hamano | 8b8b0f2 | 2007-08-26 22:10:26 | [diff] [blame] | 1853 | Another way to submit changes to a project is to tell the maintainer |
| 1854 | of that project to pull the changes from your repository using |
Junio C Hamano | ec87f52 | 2008-12-10 08:35:25 | [diff] [blame] | 1855 | linkgit:git-pull[1]. In the section "<<getting-updates-With-git-pull, |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 1856 | Getting updates with `git pull`>>" we described this as a way to get |
Junio C Hamano | 8b8b0f2 | 2007-08-26 22:10:26 | [diff] [blame] | 1857 | updates from the "main" repository, but it works just as well in the |
| 1858 | other direction. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1859 | |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 1860 | If you and the maintainer both have accounts on the same machine, then |
| 1861 | you can just pull changes from each other's repositories directly; |
Junio C Hamano | 2a8f6dc | 2007-07-09 08:48:38 | [diff] [blame] | 1862 | commands that accept repository URLs as arguments will also accept a |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 1863 | local directory name: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1864 | |
| 1865 | ------------------------------------------------- |
| 1866 | $ git clone /path/to/repository |
| 1867 | $ git pull /path/to/other/repository |
| 1868 | ------------------------------------------------- |
| 1869 | |
Junio C Hamano | 764a667 | 2007-10-23 01:23:31 | [diff] [blame] | 1870 | or an ssh URL: |
Junio C Hamano | 2a8f6dc | 2007-07-09 08:48:38 | [diff] [blame] | 1871 | |
| 1872 | ------------------------------------------------- |
| 1873 | $ git clone ssh://yourhost/~you/repository |
| 1874 | ------------------------------------------------- |
| 1875 | |
| 1876 | For projects with few developers, or for synchronizing a few private |
| 1877 | repositories, this may be all you need. |
| 1878 | |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 1879 | However, the more common way to do this is to maintain a separate public |
| 1880 | repository (usually on a different host) for others to pull changes |
| 1881 | from. This is usually more convenient, and allows you to cleanly |
| 1882 | separate private work in progress from publicly visible work. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1883 | |
| 1884 | You will continue to do your day-to-day work in your personal |
| 1885 | repository, but periodically "push" changes from your personal |
| 1886 | repository into your public repository, allowing other developers to |
| 1887 | pull from that repository. So the flow of changes, in a situation |
| 1888 | where there is one other developer with a public repository, looks |
| 1889 | like this: |
| 1890 | |
| 1891 | you push |
| 1892 | your personal repo ------------------> your public repo |
Junio C Hamano | a77a513 | 2007-06-08 16:13:44 | [diff] [blame] | 1893 | ^ | |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1894 | | | |
| 1895 | | you pull | they pull |
| 1896 | | | |
| 1897 | | | |
| 1898 | | they push V |
| 1899 | their public repo <------------------- their repo |
| 1900 | |
Junio C Hamano | 2a8f6dc | 2007-07-09 08:48:38 | [diff] [blame] | 1901 | We explain how to do this in the following sections. |
| 1902 | |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 1903 | [[setting-up-a-public-repository]] |
| 1904 | Setting up a public repository |
| 1905 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1906 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 1907 | Assume your personal repository is in the directory `~/proj`. We |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 1908 | first create a new clone of the repository and tell `git daemon` that it |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 1909 | is meant to be public: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1910 | |
| 1911 | ------------------------------------------------- |
Junio C Hamano | 91d44c5 | 2007-05-09 07:16:07 | [diff] [blame] | 1912 | $ git clone --bare ~/proj proj.git |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 1913 | $ touch proj.git/git-daemon-export-ok |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1914 | ------------------------------------------------- |
| 1915 | |
Junio C Hamano | 91d44c5 | 2007-05-09 07:16:07 | [diff] [blame] | 1916 | The resulting directory proj.git contains a "bare" git repository--it is |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 1917 | just the contents of the `.git` directory, without any files checked out |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 1918 | around it. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1919 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 1920 | Next, copy `proj.git` to the server where you plan to host the |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1921 | public repository. You can use scp, rsync, or whatever is most |
| 1922 | convenient. |
| 1923 | |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 1924 | [[exporting-via-git]] |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 1925 | Exporting a Git repository via the Git protocol |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 1926 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1927 | |
| 1928 | This is the preferred method. |
| 1929 | |
| 1930 | If someone else administers the server, they should tell you what |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 1931 | directory to put the repository in, and what `git://` URL it will |
| 1932 | appear at. You can then skip to the section |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1933 | "<<pushing-changes-to-a-public-repository,Pushing changes to a public |
| 1934 | repository>>", below. |
| 1935 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 1936 | Otherwise, all you need to do is start linkgit:git-daemon[1]; it will |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 1937 | listen on port 9418. By default, it will allow access to any directory |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 1938 | that looks like a Git directory and contains the magic file |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 1939 | git-daemon-export-ok. Passing some directory paths as `git daemon` |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 1940 | arguments will further restrict the exports to those paths. |
| 1941 | |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 1942 | You can also run `git daemon` as an inetd service; see the |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 1943 | linkgit:git-daemon[1] man page for details. (See especially the |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 1944 | examples section.) |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1945 | |
| 1946 | [[exporting-via-http]] |
Junio C Hamano | 8c5696d | 2013-02-11 05:35:00 | [diff] [blame] | 1947 | Exporting a git repository via HTTP |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 1948 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1949 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 1950 | The Git protocol gives better performance and reliability, but on a |
Junio C Hamano | 8c5696d | 2013-02-11 05:35:00 | [diff] [blame] | 1951 | host with a web server set up, HTTP exports may be simpler to set up. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1952 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 1953 | All you need to do is place the newly created bare Git repository in |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1954 | a directory that is exported by the web server, and make some |
| 1955 | adjustments to give web clients some extra information they need: |
| 1956 | |
| 1957 | ------------------------------------------------- |
| 1958 | $ mv proj.git /home/you/public_html/proj.git |
| 1959 | $ cd proj.git |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 1960 | $ git --bare update-server-info |
Junio C Hamano | c96fb5a | 2008-08-12 06:59:38 | [diff] [blame] | 1961 | $ mv hooks/post-update.sample hooks/post-update |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1962 | ------------------------------------------------- |
| 1963 | |
| 1964 | (For an explanation of the last two lines, see |
Junio C Hamano | fce7c7e | 2008-07-02 03:06:38 | [diff] [blame] | 1965 | linkgit:git-update-server-info[1] and linkgit:githooks[5].) |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1966 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 1967 | Advertise the URL of `proj.git`. Anybody else should then be able to |
Junio C Hamano | 764a667 | 2007-10-23 01:23:31 | [diff] [blame] | 1968 | clone or pull from that URL, for example with a command line like: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1969 | |
| 1970 | ------------------------------------------------- |
| 1971 | $ git clone http://yourserver.com/~you/proj.git |
| 1972 | ------------------------------------------------- |
| 1973 | |
| 1974 | (See also |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 1975 | link:howto/setup-git-server-over-http.html[setup-git-server-over-http] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1976 | for a slightly more sophisticated setup using WebDAV which also |
Junio C Hamano | 8c5696d | 2013-02-11 05:35:00 | [diff] [blame] | 1977 | allows pushing over HTTP.) |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1978 | |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1979 | [[pushing-changes-to-a-public-repository]] |
| 1980 | Pushing changes to a public repository |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 1981 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1982 | |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 1983 | Note that the two techniques outlined above (exporting via |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1984 | <<exporting-via-http,http>> or <<exporting-via-git,git>>) allow other |
| 1985 | maintainers to fetch your latest changes, but they do not allow write |
| 1986 | access, which you will need to update the public repository with the |
| 1987 | latest changes created in your private repository. |
| 1988 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 1989 | The simplest way to do this is using linkgit:git-push[1] and ssh; to |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 1990 | update the remote branch named `master` with the latest state of your |
| 1991 | branch named `master`, run |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 1992 | |
| 1993 | ------------------------------------------------- |
| 1994 | $ git push ssh://yourserver.com/~you/proj.git master:master |
| 1995 | ------------------------------------------------- |
| 1996 | |
| 1997 | or just |
| 1998 | |
| 1999 | ------------------------------------------------- |
| 2000 | $ git push ssh://yourserver.com/~you/proj.git master |
| 2001 | ------------------------------------------------- |
| 2002 | |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 2003 | As with `git fetch`, `git push` will complain if this does not result in a |
Junio C Hamano | 3f680f3 | 2009-11-16 02:10:54 | [diff] [blame] | 2004 | <<fast-forwards,fast-forward>>; see the following section for details on |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 2005 | handling this case. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2006 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 2007 | Note that the target of a `push` is normally a |
Junio C Hamano | 2a8f6dc | 2007-07-09 08:48:38 | [diff] [blame] | 2008 | <<def_bare_repository,bare>> repository. You can also push to a |
Junio C Hamano | 0292db3 | 2013-02-15 23:23:28 | [diff] [blame] | 2009 | repository that has a checked-out working tree, but a push to update the |
| 2010 | currently checked-out branch is denied by default to prevent confusion. |
Junio C Hamano | 5dab5a9 | 2013-02-25 18:51:24 | [diff] [blame] | 2011 | See the description of the receive.denyCurrentBranch option |
Junio C Hamano | 0292db3 | 2013-02-15 23:23:28 | [diff] [blame] | 2012 | in linkgit:git-config[1] for details. |
Junio C Hamano | 2a8f6dc | 2007-07-09 08:48:38 | [diff] [blame] | 2013 | |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 2014 | As with `git fetch`, you may also set up configuration options to |
Junio C Hamano | 2da4ac4 | 2013-02-19 00:41:17 | [diff] [blame] | 2015 | save typing; so, for example: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2016 | |
| 2017 | ------------------------------------------------- |
Junio C Hamano | 2da4ac4 | 2013-02-19 00:41:17 | [diff] [blame] | 2018 | $ git remote add public-repo ssh://yourserver.com/~you/proj.git |
| 2019 | ------------------------------------------------- |
| 2020 | |
| 2021 | adds the following to `.git/config`: |
| 2022 | |
| 2023 | ------------------------------------------------- |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2024 | [remote "public-repo"] |
Junio C Hamano | 2da4ac4 | 2013-02-19 00:41:17 | [diff] [blame] | 2025 | url = yourserver.com:proj.git |
| 2026 | fetch = +refs/heads/*:refs/remotes/example/* |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2027 | ------------------------------------------------- |
| 2028 | |
Junio C Hamano | 2da4ac4 | 2013-02-19 00:41:17 | [diff] [blame] | 2029 | which lets you do the same push with just |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2030 | |
| 2031 | ------------------------------------------------- |
| 2032 | $ git push public-repo master |
| 2033 | ------------------------------------------------- |
| 2034 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 2035 | See the explanations of the `remote.<name>.url`, |
| 2036 | `branch.<name>.remote`, and `remote.<name>.push` options in |
| 2037 | linkgit:git-config[1] for details. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2038 | |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 2039 | [[forcing-push]] |
| 2040 | What to do when a push fails |
| 2041 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 2042 | |
Junio C Hamano | 3f680f3 | 2009-11-16 02:10:54 | [diff] [blame] | 2043 | If a push would not result in a <<fast-forwards,fast-forward>> of the |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 2044 | remote branch, then it will fail with an error like: |
| 2045 | |
| 2046 | ------------------------------------------------- |
| 2047 | error: remote 'refs/heads/master' is not an ancestor of |
| 2048 | local 'refs/heads/master'. |
| 2049 | Maybe you are not up-to-date and need to pull first? |
| 2050 | error: failed to push to 'ssh://yourserver.com/~you/proj.git' |
| 2051 | ------------------------------------------------- |
| 2052 | |
| 2053 | This can happen, for example, if you: |
| 2054 | |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 2055 | - use `git reset --hard` to remove already-published commits, or |
| 2056 | - use `git commit --amend` to replace already-published commits |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 2057 | (as in <<fixing-a-mistake-by-rewriting-history>>), or |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 2058 | - use `git rebase` to rebase any already-published commits (as |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 2059 | in <<using-git-rebase>>). |
| 2060 | |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 2061 | You may force `git push` to perform the update anyway by preceding the |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 2062 | branch name with a plus sign: |
| 2063 | |
| 2064 | ------------------------------------------------- |
| 2065 | $ git push ssh://yourserver.com/~you/proj.git +master |
| 2066 | ------------------------------------------------- |
| 2067 | |
Junio C Hamano | 2da4ac4 | 2013-02-19 00:41:17 | [diff] [blame] | 2068 | Note the addition of the `+` sign. Alternatively, you can use the |
| 2069 | `-f` flag to force the remote update, as in: |
| 2070 | |
| 2071 | ------------------------------------------------- |
| 2072 | $ git push -f ssh://yourserver.com/~you/proj.git master |
| 2073 | ------------------------------------------------- |
| 2074 | |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 2075 | Normally whenever a branch head in a public repository is modified, it |
Junio C Hamano | 878cc1e | 2007-12-14 08:35:13 | [diff] [blame] | 2076 | is modified to point to a descendant of the commit that it pointed to |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 2077 | before. By forcing a push in this situation, you break that convention. |
Junio C Hamano | ec87f52 | 2008-12-10 08:35:25 | [diff] [blame] | 2078 | (See <<problems-With-rewriting-history>>.) |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 2079 | |
| 2080 | Nevertheless, this is a common practice for people that need a simple |
| 2081 | way to publish a work-in-progress patch series, and it is an acceptable |
| 2082 | compromise as long as you warn other developers that this is how you |
| 2083 | intend to manage the branch. |
| 2084 | |
| 2085 | It's also possible for a push to fail in this way when other people have |
| 2086 | the right to push to the same repository. In that case, the correct |
Junio C Hamano | d32738e | 2008-07-09 19:53:42 | [diff] [blame] | 2087 | solution is to retry the push after first updating your work: either by a |
| 2088 | pull, or by a fetch followed by a rebase; see the |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 2089 | <<setting-up-a-shared-repository,next section>> and |
Junio C Hamano | fce7c7e | 2008-07-02 03:06:38 | [diff] [blame] | 2090 | linkgit:gitcvs-migration[7] for more. |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 2091 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 2092 | [[setting-up-a-shared-repository]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2093 | Setting up a shared repository |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2094 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2095 | |
| 2096 | Another way to collaborate is by using a model similar to that |
| 2097 | commonly used in CVS, where several developers with special rights |
| 2098 | all push to and pull from a single shared repository. See |
Junio C Hamano | fce7c7e | 2008-07-02 03:06:38 | [diff] [blame] | 2099 | linkgit:gitcvs-migration[7] for instructions on how to |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2100 | set this up. |
| 2101 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 2102 | However, while there is nothing wrong with Git's support for shared |
Junio C Hamano | ed7f4f6 | 2007-05-20 09:09:09 | [diff] [blame] | 2103 | repositories, this mode of operation is not generally recommended, |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 2104 | simply because the mode of collaboration that Git supports--by |
Junio C Hamano | ed7f4f6 | 2007-05-20 09:09:09 | [diff] [blame] | 2105 | exchanging patches and pulling from public repositories--has so many |
| 2106 | advantages over the central shared repository: |
| 2107 | |
| 2108 | - Git's ability to quickly import and merge patches allows a |
| 2109 | single maintainer to process incoming changes even at very |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 2110 | high rates. And when that becomes too much, `git pull` provides |
Junio C Hamano | ed7f4f6 | 2007-05-20 09:09:09 | [diff] [blame] | 2111 | an easy way for that maintainer to delegate this job to other |
| 2112 | maintainers while still allowing optional review of incoming |
| 2113 | changes. |
| 2114 | - Since every developer's repository has the same complete copy |
| 2115 | of the project history, no repository is special, and it is |
| 2116 | trivial for another developer to take over maintenance of a |
| 2117 | project, either by mutual agreement, or because a maintainer |
| 2118 | becomes unresponsive or difficult to work with. |
| 2119 | - The lack of a central group of "committers" means there is |
| 2120 | less need for formal decisions about who is "in" and who is |
| 2121 | "out". |
| 2122 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 2123 | [[setting-up-gitweb]] |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2124 | Allowing web browsing of a repository |
| 2125 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2126 | |
| 2127 | The gitweb cgi script provides users an easy way to browse your |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 2128 | project's files and history without having to install Git; see the file |
| 2129 | gitweb/INSTALL in the Git source tree for instructions on setting it up. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2130 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 2131 | [[sharing-development-examples]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2132 | Examples |
| 2133 | -------- |
| 2134 | |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2135 | [[maintaining-topic-branches]] |
| 2136 | Maintaining topic branches for a Linux subsystem maintainer |
| 2137 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 2138 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 2139 | This describes how Tony Luck uses Git in his role as maintainer of the |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2140 | IA64 architecture for the Linux kernel. |
| 2141 | |
| 2142 | He uses two public branches: |
| 2143 | |
| 2144 | - A "test" tree into which patches are initially placed so that they |
| 2145 | can get some exposure when integrated with other ongoing development. |
| 2146 | This tree is available to Andrew for pulling into -mm whenever he |
| 2147 | wants. |
| 2148 | |
| 2149 | - A "release" tree into which tested patches are moved for final sanity |
| 2150 | checking, and as a vehicle to send them upstream to Linus (by sending |
| 2151 | him a "please pull" request.) |
| 2152 | |
| 2153 | He also uses a set of temporary branches ("topic branches"), each |
| 2154 | containing a logical grouping of patches. |
| 2155 | |
| 2156 | To set this up, first create your work tree by cloning Linus's public |
| 2157 | tree: |
| 2158 | |
| 2159 | ------------------------------------------------- |
Junio C Hamano | a195230 | 2013-07-01 21:31:18 | [diff] [blame] | 2160 | $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git work |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2161 | $ cd work |
| 2162 | ------------------------------------------------- |
| 2163 | |
Junio C Hamano | 97bcb48 | 2010-11-25 03:16:07 | [diff] [blame] | 2164 | Linus's tree will be stored in the remote-tracking branch named origin/master, |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 2165 | and can be updated using linkgit:git-fetch[1]; you can track other |
| 2166 | public trees using linkgit:git-remote[1] to set up a "remote" and |
| 2167 | linkgit:git-fetch[1] to keep them up-to-date; see |
Junio C Hamano | 8b8b0f2 | 2007-08-26 22:10:26 | [diff] [blame] | 2168 | <<repositories-and-branches>>. |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2169 | |
| 2170 | Now create the branches in which you are going to work; these start out |
| 2171 | at the current tip of origin/master branch, and should be set up (using |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 2172 | the `--track` option to linkgit:git-branch[1]) to merge changes in from |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2173 | Linus by default. |
| 2174 | |
| 2175 | ------------------------------------------------- |
| 2176 | $ git branch --track test origin/master |
| 2177 | $ git branch --track release origin/master |
| 2178 | ------------------------------------------------- |
| 2179 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 2180 | These can be easily kept up to date using linkgit:git-pull[1]. |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2181 | |
| 2182 | ------------------------------------------------- |
| 2183 | $ git checkout test && git pull |
| 2184 | $ git checkout release && git pull |
| 2185 | ------------------------------------------------- |
| 2186 | |
| 2187 | Important note! If you have any local changes in these branches, then |
| 2188 | this merge will create a commit object in the history (with no local |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 2189 | changes Git will simply do a "fast-forward" merge). Many people dislike |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2190 | the "noise" that this creates in the Linux history, so you should avoid |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 2191 | doing this capriciously in the `release` branch, as these noisy commits |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2192 | will become part of the permanent history when you ask Linus to pull |
| 2193 | from the release branch. |
| 2194 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 2195 | A few configuration variables (see linkgit:git-config[1]) can |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2196 | make it easy to push both branches to your public tree. (See |
| 2197 | <<setting-up-a-public-repository>>.) |
| 2198 | |
| 2199 | ------------------------------------------------- |
| 2200 | $ cat >> .git/config <<EOF |
| 2201 | [remote "mytree"] |
Junio C Hamano | a195230 | 2013-07-01 21:31:18 | [diff] [blame] | 2202 | url = master.kernel.org:/pub/scm/linux/kernel/git/aegl/linux.git |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2203 | push = release |
| 2204 | push = test |
| 2205 | EOF |
| 2206 | ------------------------------------------------- |
| 2207 | |
| 2208 | Then you can push both the test and release trees using |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 2209 | linkgit:git-push[1]: |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2210 | |
| 2211 | ------------------------------------------------- |
| 2212 | $ git push mytree |
| 2213 | ------------------------------------------------- |
| 2214 | |
| 2215 | or push just one of the test and release branches using: |
| 2216 | |
| 2217 | ------------------------------------------------- |
| 2218 | $ git push mytree test |
| 2219 | ------------------------------------------------- |
| 2220 | |
| 2221 | or |
| 2222 | |
| 2223 | ------------------------------------------------- |
| 2224 | $ git push mytree release |
| 2225 | ------------------------------------------------- |
| 2226 | |
| 2227 | Now to apply some patches from the community. Think of a short |
| 2228 | snappy name for a branch to hold this patch (or related group of |
Junio C Hamano | c27b733 | 2010-10-14 04:37:28 | [diff] [blame] | 2229 | patches), and create a new branch from a recent stable tag of |
| 2230 | Linus's branch. Picking a stable base for your branch will: |
| 2231 | 1) help you: by avoiding inclusion of unrelated and perhaps lightly |
| 2232 | tested changes |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 2233 | 2) help future bug hunters that use `git bisect` to find problems |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2234 | |
| 2235 | ------------------------------------------------- |
Junio C Hamano | c27b733 | 2010-10-14 04:37:28 | [diff] [blame] | 2236 | $ git checkout -b speed-up-spinlocks v2.6.35 |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2237 | ------------------------------------------------- |
| 2238 | |
| 2239 | Now you apply the patch(es), run some tests, and commit the change(s). If |
| 2240 | the patch is a multi-part series, then you should apply each as a separate |
| 2241 | commit to this branch. |
| 2242 | |
| 2243 | ------------------------------------------------- |
| 2244 | $ ... patch ... test ... commit [ ... patch ... test ... commit ]* |
| 2245 | ------------------------------------------------- |
| 2246 | |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 2247 | When you are happy with the state of this change, you can merge it into the |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2248 | "test" branch in preparation to make it public: |
| 2249 | |
| 2250 | ------------------------------------------------- |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 2251 | $ git checkout test && git merge speed-up-spinlocks |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2252 | ------------------------------------------------- |
| 2253 | |
| 2254 | It is unlikely that you would have any conflicts here ... but you might if you |
| 2255 | spent a while on this step and had also pulled new versions from upstream. |
| 2256 | |
Junio C Hamano | c8c398a | 2014-06-16 21:14:05 | [diff] [blame] | 2257 | Sometime later when enough time has passed and testing done, you can pull the |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 2258 | same branch into the `release` tree ready to go upstream. This is where you |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2259 | see the value of keeping each patch (or patch series) in its own branch. It |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 2260 | means that the patches can be moved into the `release` tree in any order. |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2261 | |
| 2262 | ------------------------------------------------- |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 2263 | $ git checkout release && git merge speed-up-spinlocks |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2264 | ------------------------------------------------- |
| 2265 | |
| 2266 | After a while, you will have a number of branches, and despite the |
| 2267 | well chosen names you picked for each of them, you may forget what |
| 2268 | they are for, or what status they are in. To get a reminder of what |
| 2269 | changes are in a specific branch, use: |
| 2270 | |
| 2271 | ------------------------------------------------- |
Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 2272 | $ git log linux..branchname | git shortlog |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2273 | ------------------------------------------------- |
| 2274 | |
Junio C Hamano | 764a667 | 2007-10-23 01:23:31 | [diff] [blame] | 2275 | To see whether it has already been merged into the test or release branches, |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2276 | use: |
| 2277 | |
| 2278 | ------------------------------------------------- |
| 2279 | $ git log test..branchname |
| 2280 | ------------------------------------------------- |
| 2281 | |
| 2282 | or |
| 2283 | |
| 2284 | ------------------------------------------------- |
| 2285 | $ git log release..branchname |
| 2286 | ------------------------------------------------- |
| 2287 | |
Junio C Hamano | 764a667 | 2007-10-23 01:23:31 | [diff] [blame] | 2288 | (If this branch has not yet been merged, you will see some log entries. |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2289 | If it has been merged, then there will be no output.) |
| 2290 | |
| 2291 | Once a patch completes the great cycle (moving from test to release, |
| 2292 | then pulled by Linus, and finally coming back into your local |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 2293 | `origin/master` branch), the branch for this change is no longer needed. |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2294 | You detect this when the output from: |
| 2295 | |
| 2296 | ------------------------------------------------- |
| 2297 | $ git log origin..branchname |
| 2298 | ------------------------------------------------- |
| 2299 | |
| 2300 | is empty. At this point the branch can be deleted: |
| 2301 | |
| 2302 | ------------------------------------------------- |
| 2303 | $ git branch -d branchname |
| 2304 | ------------------------------------------------- |
| 2305 | |
| 2306 | Some changes are so trivial that it is not necessary to create a separate |
| 2307 | branch and then merge into each of the test and release branches. For |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 2308 | these changes, just apply directly to the `release` branch, and then |
| 2309 | merge that into the `test` branch. |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2310 | |
Junio C Hamano | 5dab5a9 | 2013-02-25 18:51:24 | [diff] [blame] | 2311 | After pushing your work to `mytree`, you can use |
| 2312 | linkgit:git-request-pull[1] to prepare a "please pull" request message |
| 2313 | to send to Linus: |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2314 | |
| 2315 | ------------------------------------------------- |
Junio C Hamano | 5dab5a9 | 2013-02-25 18:51:24 | [diff] [blame] | 2316 | $ git push mytree |
| 2317 | $ git request-pull origin mytree release |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2318 | ------------------------------------------------- |
| 2319 | |
| 2320 | Here are some of the scripts that simplify all this even further. |
| 2321 | |
| 2322 | ------------------------------------------------- |
| 2323 | ==== update script ==== |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 2324 | # Update a branch in my Git tree. If the branch to be updated |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2325 | # is origin, then pull from kernel.org. Otherwise merge |
| 2326 | # origin/master branch into test|release branch |
| 2327 | |
| 2328 | case "$1" in |
| 2329 | test|release) |
| 2330 | git checkout $1 && git pull . origin |
| 2331 | ;; |
| 2332 | origin) |
Junio C Hamano | 9810d63 | 2007-09-24 01:05:34 | [diff] [blame] | 2333 | before=$(git rev-parse refs/remotes/origin/master) |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2334 | git fetch origin |
Junio C Hamano | 9810d63 | 2007-09-24 01:05:34 | [diff] [blame] | 2335 | after=$(git rev-parse refs/remotes/origin/master) |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2336 | if [ $before != $after ] |
| 2337 | then |
| 2338 | git log $before..$after | git shortlog |
| 2339 | fi |
| 2340 | ;; |
| 2341 | *) |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 2342 | echo "usage: $0 origin|test|release" 1>&2 |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2343 | exit 1 |
| 2344 | ;; |
| 2345 | esac |
| 2346 | ------------------------------------------------- |
| 2347 | |
| 2348 | ------------------------------------------------- |
| 2349 | ==== merge script ==== |
| 2350 | # Merge a branch into either the test or release branch |
| 2351 | |
| 2352 | pname=$0 |
| 2353 | |
| 2354 | usage() |
| 2355 | { |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 2356 | echo "usage: $pname branch test|release" 1>&2 |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2357 | exit 1 |
| 2358 | } |
| 2359 | |
Junio C Hamano | 9810d63 | 2007-09-24 01:05:34 | [diff] [blame] | 2360 | git show-ref -q --verify -- refs/heads/"$1" || { |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2361 | echo "Can't see branch <$1>" 1>&2 |
| 2362 | usage |
Junio C Hamano | 9810d63 | 2007-09-24 01:05:34 | [diff] [blame] | 2363 | } |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2364 | |
| 2365 | case "$2" in |
| 2366 | test|release) |
| 2367 | if [ $(git log $2..$1 | wc -c) -eq 0 ] |
| 2368 | then |
| 2369 | echo $1 already merged into $2 1>&2 |
| 2370 | exit 1 |
| 2371 | fi |
| 2372 | git checkout $2 && git pull . $1 |
| 2373 | ;; |
| 2374 | *) |
| 2375 | usage |
| 2376 | ;; |
| 2377 | esac |
| 2378 | ------------------------------------------------- |
| 2379 | |
| 2380 | ------------------------------------------------- |
| 2381 | ==== status script ==== |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 2382 | # report on status of my ia64 Git tree |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2383 | |
| 2384 | gb=$(tput setab 2) |
| 2385 | rb=$(tput setab 1) |
| 2386 | restore=$(tput setab 9) |
| 2387 | |
| 2388 | if [ `git rev-list test..release | wc -c` -gt 0 ] |
| 2389 | then |
| 2390 | echo $rb Warning: commits in release that are not in test $restore |
| 2391 | git log test..release |
| 2392 | fi |
| 2393 | |
Junio C Hamano | 9810d63 | 2007-09-24 01:05:34 | [diff] [blame] | 2394 | for branch in `git show-ref --heads | sed 's|^.*/||'` |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 2395 | do |
| 2396 | if [ $branch = test -o $branch = release ] |
| 2397 | then |
| 2398 | continue |
| 2399 | fi |
| 2400 | |
| 2401 | echo -n $gb ======= $branch ====== $restore " " |
| 2402 | status= |
| 2403 | for ref in test release origin/master |
| 2404 | do |
| 2405 | if [ `git rev-list $ref..$branch | wc -c` -gt 0 ] |
| 2406 | then |
| 2407 | status=$status${ref:0:1} |
| 2408 | fi |
| 2409 | done |
| 2410 | case $status in |
| 2411 | trl) |
| 2412 | echo $rb Need to pull into test $restore |
| 2413 | ;; |
| 2414 | rl) |
| 2415 | echo "In test" |
| 2416 | ;; |
| 2417 | l) |
| 2418 | echo "Waiting for linus" |
| 2419 | ;; |
| 2420 | "") |
| 2421 | echo $rb All done $restore |
| 2422 | ;; |
| 2423 | *) |
| 2424 | echo $rb "<$status>" $restore |
| 2425 | ;; |
| 2426 | esac |
| 2427 | git log origin/master..$branch | git shortlog |
| 2428 | done |
| 2429 | ------------------------------------------------- |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2430 | |
| 2431 | |
| 2432 | [[cleaning-up-history]] |
| 2433 | Rewriting history and maintaining patch series |
| 2434 | ============================================== |
| 2435 | |
| 2436 | Normally commits are only added to a project, never taken away or |
| 2437 | replaced. Git is designed with this assumption, and violating it will |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 2438 | cause Git's merge machinery (for example) to do the wrong thing. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2439 | |
| 2440 | However, there is a situation in which it can be useful to violate this |
| 2441 | assumption. |
| 2442 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 2443 | [[patch-series]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2444 | Creating the perfect patch series |
| 2445 | --------------------------------- |
| 2446 | |
| 2447 | Suppose you are a contributor to a large project, and you want to add a |
| 2448 | complicated feature, and to present it to the other developers in a way |
| 2449 | that makes it easy for them to read your changes, verify that they are |
| 2450 | correct, and understand why you made each change. |
| 2451 | |
| 2452 | If you present all of your changes as a single patch (or commit), they |
Junio C Hamano | db911ee | 2007-02-28 08:13:52 | [diff] [blame] | 2453 | may find that it is too much to digest all at once. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2454 | |
| 2455 | If you present them with the entire history of your work, complete with |
| 2456 | mistakes, corrections, and dead ends, they may be overwhelmed. |
| 2457 | |
| 2458 | So the ideal is usually to produce a series of patches such that: |
| 2459 | |
| 2460 | 1. Each patch can be applied in order. |
| 2461 | |
| 2462 | 2. Each patch includes a single logical change, together with a |
| 2463 | message explaining the change. |
| 2464 | |
| 2465 | 3. No patch introduces a regression: after applying any initial |
| 2466 | part of the series, the resulting project still compiles and |
| 2467 | works, and has no bugs that it didn't have before. |
| 2468 | |
| 2469 | 4. The complete series produces the same end result as your own |
| 2470 | (probably much messier!) development process did. |
| 2471 | |
| 2472 | We will introduce some tools that can help you do this, explain how to |
| 2473 | use them, and then explain some of the problems that can arise because |
| 2474 | you are rewriting history. |
| 2475 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 2476 | [[using-git-rebase]] |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 2477 | Keeping a patch series up to date using git rebase |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2478 | -------------------------------------------------- |
| 2479 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 2480 | Suppose that you create a branch `mywork` on a remote-tracking branch |
| 2481 | `origin`, and create some commits on top of it: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2482 | |
| 2483 | ------------------------------------------------- |
| 2484 | $ git checkout -b mywork origin |
| 2485 | $ vi file.txt |
| 2486 | $ git commit |
| 2487 | $ vi otherfile.txt |
| 2488 | $ git commit |
| 2489 | ... |
| 2490 | ------------------------------------------------- |
| 2491 | |
| 2492 | You have performed no merges into mywork, so it is just a simple linear |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 2493 | sequence of patches on top of `origin`: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2494 | |
Junio C Hamano | c51fede | 2007-03-12 07:29:20 | [diff] [blame] | 2495 | ................................................ |
Junio C Hamano | 3b4609d | 2010-09-30 00:04:34 | [diff] [blame] | 2496 | o--o--O <-- origin |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2497 | \ |
Junio C Hamano | 3b4609d | 2010-09-30 00:04:34 | [diff] [blame] | 2498 | a--b--c <-- mywork |
Junio C Hamano | c51fede | 2007-03-12 07:29:20 | [diff] [blame] | 2499 | ................................................ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2500 | |
| 2501 | Some more interesting work has been done in the upstream project, and |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 2502 | `origin` has advanced: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2503 | |
Junio C Hamano | c51fede | 2007-03-12 07:29:20 | [diff] [blame] | 2504 | ................................................ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2505 | o--o--O--o--o--o <-- origin |
| 2506 | \ |
| 2507 | a--b--c <-- mywork |
Junio C Hamano | c51fede | 2007-03-12 07:29:20 | [diff] [blame] | 2508 | ................................................ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2509 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 2510 | At this point, you could use `pull` to merge your changes back in; |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2511 | the result would create a new merge commit, like this: |
| 2512 | |
Junio C Hamano | c51fede | 2007-03-12 07:29:20 | [diff] [blame] | 2513 | ................................................ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2514 | o--o--O--o--o--o <-- origin |
| 2515 | \ \ |
| 2516 | a--b--c--m <-- mywork |
Junio C Hamano | c51fede | 2007-03-12 07:29:20 | [diff] [blame] | 2517 | ................................................ |
Junio C Hamano | a77a513 | 2007-06-08 16:13:44 | [diff] [blame] | 2518 | |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2519 | However, if you prefer to keep the history in mywork a simple series of |
| 2520 | commits without any merges, you may instead choose to use |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 2521 | linkgit:git-rebase[1]: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2522 | |
| 2523 | ------------------------------------------------- |
| 2524 | $ git checkout mywork |
| 2525 | $ git rebase origin |
| 2526 | ------------------------------------------------- |
| 2527 | |
| 2528 | This will remove each of your commits from mywork, temporarily saving |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 2529 | them as patches (in a directory named `.git/rebase-apply`), update mywork to |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2530 | point at the latest version of origin, then apply each of the saved |
| 2531 | patches to the new mywork. The result will look like: |
| 2532 | |
| 2533 | |
Junio C Hamano | c51fede | 2007-03-12 07:29:20 | [diff] [blame] | 2534 | ................................................ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2535 | o--o--O--o--o--o <-- origin |
| 2536 | \ |
| 2537 | a'--b'--c' <-- mywork |
Junio C Hamano | c51fede | 2007-03-12 07:29:20 | [diff] [blame] | 2538 | ................................................ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2539 | |
| 2540 | In the process, it may discover conflicts. In that case it will stop |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 2541 | and allow you to fix the conflicts; after fixing conflicts, use `git add` |
Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 2542 | to update the index with those contents, and then, instead of |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 2543 | running `git commit`, just run |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2544 | |
| 2545 | ------------------------------------------------- |
| 2546 | $ git rebase --continue |
| 2547 | ------------------------------------------------- |
| 2548 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 2549 | and Git will continue applying the rest of the patches. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2550 | |
Junio C Hamano | 764a667 | 2007-10-23 01:23:31 | [diff] [blame] | 2551 | At any point you may use the `--abort` option to abort this process and |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2552 | return mywork to the state it had before you started the rebase: |
| 2553 | |
| 2554 | ------------------------------------------------- |
| 2555 | $ git rebase --abort |
| 2556 | ------------------------------------------------- |
| 2557 | |
Junio C Hamano | 5dab5a9 | 2013-02-25 18:51:24 | [diff] [blame] | 2558 | If you need to reorder or edit a number of commits in a branch, it may |
| 2559 | be easier to use `git rebase -i`, which allows you to reorder and |
| 2560 | squash commits, as well as marking them for individual editing during |
| 2561 | the rebase. See <<interactive-rebase>> for details, and |
| 2562 | <<reordering-patch-series>> for alternatives. |
| 2563 | |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 2564 | [[rewriting-one-commit]] |
| 2565 | Rewriting a single commit |
Junio C Hamano | aa83a7d | 2007-03-05 02:37:29 | [diff] [blame] | 2566 | ------------------------- |
| 2567 | |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 2568 | We saw in <<fixing-a-mistake-by-rewriting-history>> that you can replace the |
Junio C Hamano | aa83a7d | 2007-03-05 02:37:29 | [diff] [blame] | 2569 | most recent commit using |
| 2570 | |
| 2571 | ------------------------------------------------- |
| 2572 | $ git commit --amend |
| 2573 | ------------------------------------------------- |
| 2574 | |
| 2575 | which will replace the old commit by a new commit incorporating your |
| 2576 | changes, giving you a chance to edit the old commit message first. |
Junio C Hamano | 5dab5a9 | 2013-02-25 18:51:24 | [diff] [blame] | 2577 | This is useful for fixing typos in your last commit, or for adjusting |
| 2578 | the patch contents of a poorly staged commit. |
Junio C Hamano | aa83a7d | 2007-03-05 02:37:29 | [diff] [blame] | 2579 | |
Junio C Hamano | 5dab5a9 | 2013-02-25 18:51:24 | [diff] [blame] | 2580 | If you need to amend commits from deeper in your history, you can |
| 2581 | use <<interactive-rebase,interactive rebase's `edit` instruction>>. |
Junio C Hamano | aa83a7d | 2007-03-05 02:37:29 | [diff] [blame] | 2582 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 2583 | [[reordering-patch-series]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2584 | Reordering or selecting from a patch series |
| 2585 | ------------------------------------------- |
| 2586 | |
Junio C Hamano | 5dab5a9 | 2013-02-25 18:51:24 | [diff] [blame] | 2587 | Sometimes you want to edit a commit deeper in your history. One |
| 2588 | approach is to use `git format-patch` to create a series of patches |
| 2589 | and then reset the state to before the patches: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2590 | |
| 2591 | ------------------------------------------------- |
| 2592 | $ git format-patch origin |
| 2593 | $ git reset --hard origin |
| 2594 | ------------------------------------------------- |
| 2595 | |
Junio C Hamano | 5dab5a9 | 2013-02-25 18:51:24 | [diff] [blame] | 2596 | Then modify, reorder, or eliminate patches as needed before applying |
| 2597 | them again with linkgit:git-am[1]: |
| 2598 | |
| 2599 | ------------------------------------------------- |
| 2600 | $ git am *.patch |
| 2601 | ------------------------------------------------- |
| 2602 | |
| 2603 | [[interactive-rebase]] |
| 2604 | Using interactive rebases |
| 2605 | ------------------------- |
| 2606 | |
| 2607 | You can also edit a patch series with an interactive rebase. This is |
| 2608 | the same as <<reordering-patch-series,reordering a patch series using |
| 2609 | `format-patch`>>, so use whichever interface you like best. |
| 2610 | |
| 2611 | Rebase your current HEAD on the last commit you want to retain as-is. |
| 2612 | For example, if you want to reorder the last 5 commits, use: |
| 2613 | |
| 2614 | ------------------------------------------------- |
| 2615 | $ git rebase -i HEAD~5 |
| 2616 | ------------------------------------------------- |
| 2617 | |
| 2618 | This will open your editor with a list of steps to be taken to perform |
| 2619 | your rebase. |
| 2620 | |
| 2621 | ------------------------------------------------- |
| 2622 | pick deadbee The oneline of this commit |
| 2623 | pick fa1afe1 The oneline of the next commit |
| 2624 | ... |
| 2625 | |
| 2626 | # Rebase c0ffeee..deadbee onto c0ffeee |
| 2627 | # |
| 2628 | # Commands: |
| 2629 | # p, pick = use commit |
| 2630 | # r, reword = use commit, but edit the commit message |
| 2631 | # e, edit = use commit, but stop for amending |
| 2632 | # s, squash = use commit, but meld into previous commit |
| 2633 | # f, fixup = like "squash", but discard this commit's log message |
| 2634 | # x, exec = run command (the rest of the line) using shell |
| 2635 | # |
| 2636 | # These lines can be re-ordered; they are executed from top to bottom. |
| 2637 | # |
| 2638 | # If you remove a line here THAT COMMIT WILL BE LOST. |
| 2639 | # |
| 2640 | # However, if you remove everything, the rebase will be aborted. |
| 2641 | # |
| 2642 | # Note that empty commits are commented out |
| 2643 | ------------------------------------------------- |
| 2644 | |
| 2645 | As explained in the comments, you can reorder commits, squash them |
| 2646 | together, edit commit messages, etc. by editing the list. Once you |
| 2647 | are satisfied, save the list and close your editor, and the rebase |
| 2648 | will begin. |
| 2649 | |
| 2650 | The rebase will stop where `pick` has been replaced with `edit` or |
| 2651 | when a step in the list fails to mechanically resolve conflicts and |
| 2652 | needs your help. When you are done editing and/or resolving conflicts |
| 2653 | you can continue with `git rebase --continue`. If you decide that |
| 2654 | things are getting too hairy, you can always bail out with `git rebase |
| 2655 | --abort`. Even after the rebase is complete, you can still recover |
| 2656 | the original branch by using the <<reflogs,reflog>>. |
| 2657 | |
| 2658 | For a more detailed discussion of the procedure and additional tips, |
| 2659 | see the "INTERACTIVE MODE" section of linkgit:git-rebase[1]. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2660 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 2661 | [[patch-series-tools]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2662 | Other tools |
| 2663 | ----------- |
| 2664 | |
Junio C Hamano | bf984de | 2009-11-23 06:11:19 | [diff] [blame] | 2665 | There are numerous other tools, such as StGit, which exist for the |
Junio C Hamano | db911ee | 2007-02-28 08:13:52 | [diff] [blame] | 2666 | purpose of maintaining a patch series. These are outside of the scope of |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2667 | this manual. |
| 2668 | |
Junio C Hamano | ec87f52 | 2008-12-10 08:35:25 | [diff] [blame] | 2669 | [[problems-With-rewriting-history]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2670 | Problems with rewriting history |
| 2671 | ------------------------------- |
| 2672 | |
| 2673 | The primary problem with rewriting the history of a branch has to do |
| 2674 | with merging. Suppose somebody fetches your branch and merges it into |
| 2675 | their branch, with a result something like this: |
| 2676 | |
Junio C Hamano | c51fede | 2007-03-12 07:29:20 | [diff] [blame] | 2677 | ................................................ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2678 | o--o--O--o--o--o <-- origin |
| 2679 | \ \ |
| 2680 | t--t--t--m <-- their branch: |
Junio C Hamano | c51fede | 2007-03-12 07:29:20 | [diff] [blame] | 2681 | ................................................ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2682 | |
| 2683 | Then suppose you modify the last three commits: |
| 2684 | |
Junio C Hamano | c51fede | 2007-03-12 07:29:20 | [diff] [blame] | 2685 | ................................................ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2686 | o--o--o <-- new head of origin |
| 2687 | / |
| 2688 | o--o--O--o--o--o <-- old head of origin |
Junio C Hamano | c51fede | 2007-03-12 07:29:20 | [diff] [blame] | 2689 | ................................................ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2690 | |
| 2691 | If we examined all this history together in one repository, it will |
| 2692 | look like: |
| 2693 | |
Junio C Hamano | c51fede | 2007-03-12 07:29:20 | [diff] [blame] | 2694 | ................................................ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2695 | o--o--o <-- new head of origin |
| 2696 | / |
| 2697 | o--o--O--o--o--o <-- old head of origin |
| 2698 | \ \ |
| 2699 | t--t--t--m <-- their branch: |
Junio C Hamano | c51fede | 2007-03-12 07:29:20 | [diff] [blame] | 2700 | ................................................ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2701 | |
| 2702 | Git has no way of knowing that the new head is an updated version of |
| 2703 | the old head; it treats this situation exactly the same as it would if |
| 2704 | two developers had independently done the work on the old and new heads |
| 2705 | in parallel. At this point, if someone attempts to merge the new head |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 2706 | in to their branch, Git will attempt to merge together the two (old and |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2707 | new) lines of development, instead of trying to replace the old by the |
| 2708 | new. The results are likely to be unexpected. |
| 2709 | |
| 2710 | You may still choose to publish branches whose history is rewritten, |
| 2711 | and it may be useful for others to be able to fetch those branches in |
| 2712 | order to examine or test them, but they should not attempt to pull such |
| 2713 | branches into their own work. |
| 2714 | |
| 2715 | For true distributed development that supports proper merging, |
| 2716 | published branches should never be rewritten. |
| 2717 | |
Junio C Hamano | 393e57f | 2007-11-20 04:53:25 | [diff] [blame] | 2718 | [[bisect-merges]] |
| 2719 | Why bisecting merge commits can be harder than bisecting linear history |
| 2720 | ----------------------------------------------------------------------- |
| 2721 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 2722 | The linkgit:git-bisect[1] command correctly handles history that |
Junio C Hamano | 393e57f | 2007-11-20 04:53:25 | [diff] [blame] | 2723 | includes merge commits. However, when the commit that it finds is a |
| 2724 | merge commit, the user may need to work harder than usual to figure out |
| 2725 | why that commit introduced a problem. |
| 2726 | |
| 2727 | Imagine this history: |
| 2728 | |
| 2729 | ................................................ |
| 2730 | ---Z---o---X---...---o---A---C---D |
| 2731 | \ / |
| 2732 | o---o---Y---...---o---B |
| 2733 | ................................................ |
| 2734 | |
| 2735 | Suppose that on the upper line of development, the meaning of one |
| 2736 | of the functions that exists at Z is changed at commit X. The |
| 2737 | commits from Z leading to A change both the function's |
| 2738 | implementation and all calling sites that exist at Z, as well |
| 2739 | as new calling sites they add, to be consistent. There is no |
| 2740 | bug at A. |
| 2741 | |
| 2742 | Suppose that in the meantime on the lower line of development somebody |
| 2743 | adds a new calling site for that function at commit Y. The |
| 2744 | commits from Z leading to B all assume the old semantics of that |
| 2745 | function and the callers and the callee are consistent with each |
| 2746 | other. There is no bug at B, either. |
| 2747 | |
| 2748 | Suppose further that the two development lines merge cleanly at C, |
| 2749 | so no conflict resolution is required. |
| 2750 | |
| 2751 | Nevertheless, the code at C is broken, because the callers added |
| 2752 | on the lower line of development have not been converted to the new |
| 2753 | semantics introduced on the upper line of development. So if all |
| 2754 | you know is that D is bad, that Z is good, and that |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 2755 | linkgit:git-bisect[1] identifies C as the culprit, how will you |
Junio C Hamano | 393e57f | 2007-11-20 04:53:25 | [diff] [blame] | 2756 | figure out that the problem is due to this change in semantics? |
| 2757 | |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 2758 | When the result of a `git bisect` is a non-merge commit, you should |
Junio C Hamano | 393e57f | 2007-11-20 04:53:25 | [diff] [blame] | 2759 | normally be able to discover the problem by examining just that commit. |
| 2760 | Developers can make this easy by breaking their changes into small |
| 2761 | self-contained commits. That won't help in the case above, however, |
| 2762 | because the problem isn't obvious from examination of any single |
| 2763 | commit; instead, a global view of the development is required. To |
| 2764 | make matters worse, the change in semantics in the problematic |
| 2765 | function may be just one small part of the changes in the upper |
| 2766 | line of development. |
| 2767 | |
| 2768 | On the other hand, if instead of merging at C you had rebased the |
| 2769 | history between Z to B on top of A, you would have gotten this |
| 2770 | linear history: |
| 2771 | |
| 2772 | ................................................................ |
| 2773 | ---Z---o---X--...---o---A---o---o---Y*--...---o---B*--D* |
| 2774 | ................................................................ |
| 2775 | |
| 2776 | Bisecting between Z and D* would hit a single culprit commit Y*, |
| 2777 | and understanding why Y* was broken would probably be easier. |
| 2778 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 2779 | Partly for this reason, many experienced Git users, even when |
Junio C Hamano | 393e57f | 2007-11-20 04:53:25 | [diff] [blame] | 2780 | working on an otherwise merge-heavy project, keep the history |
| 2781 | linear by rebasing against the latest upstream version before |
| 2782 | publishing. |
| 2783 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 2784 | [[advanced-branch-management]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2785 | Advanced branch management |
| 2786 | ========================== |
| 2787 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 2788 | [[fetching-individual-branches]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2789 | Fetching individual branches |
| 2790 | ---------------------------- |
| 2791 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 2792 | Instead of using linkgit:git-remote[1], you can also choose just |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2793 | to update one branch at a time, and to store it locally under an |
| 2794 | arbitrary name: |
| 2795 | |
| 2796 | ------------------------------------------------- |
| 2797 | $ git fetch origin todo:my-todo-work |
| 2798 | ------------------------------------------------- |
| 2799 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 2800 | The first argument, `origin`, just tells Git to fetch from the |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 2801 | repository you originally cloned from. The second argument tells Git |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 2802 | to fetch the branch named `todo` from the remote repository, and to |
| 2803 | store it locally under the name `refs/heads/my-todo-work`. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2804 | |
| 2805 | You can also fetch branches from other repositories; so |
| 2806 | |
| 2807 | ------------------------------------------------- |
| 2808 | $ git fetch git://example.com/proj.git master:example-master |
| 2809 | ------------------------------------------------- |
| 2810 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 2811 | will create a new branch named `example-master` and store in it the |
| 2812 | branch named `master` from the repository at the given URL. If you |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2813 | already have a branch named example-master, it will attempt to |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 2814 | <<fast-forwards,fast-forward>> to the commit given by example.com's |
| 2815 | master branch. In more detail: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2816 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 2817 | [[fetch-fast-forwards]] |
| 2818 | git fetch and fast-forwards |
| 2819 | --------------------------- |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2820 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 2821 | In the previous example, when updating an existing branch, `git fetch` |
Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 2822 | checks to make sure that the most recent commit on the remote |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2823 | branch is a descendant of the most recent commit on your copy of the |
| 2824 | branch before updating your copy of the branch to point at the new |
Junio C Hamano | 3f680f3 | 2009-11-16 02:10:54 | [diff] [blame] | 2825 | commit. Git calls this process a <<fast-forwards,fast-forward>>. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2826 | |
Junio C Hamano | 3f680f3 | 2009-11-16 02:10:54 | [diff] [blame] | 2827 | A fast-forward looks something like this: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2828 | |
Junio C Hamano | c51fede | 2007-03-12 07:29:20 | [diff] [blame] | 2829 | ................................................ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2830 | o--o--o--o <-- old head of the branch |
| 2831 | \ |
| 2832 | o--o--o <-- new head of the branch |
Junio C Hamano | c51fede | 2007-03-12 07:29:20 | [diff] [blame] | 2833 | ................................................ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2834 | |
| 2835 | |
| 2836 | In some cases it is possible that the new head will *not* actually be |
| 2837 | a descendant of the old head. For example, the developer may have |
| 2838 | realized she made a serious mistake, and decided to backtrack, |
| 2839 | resulting in a situation like: |
| 2840 | |
Junio C Hamano | c51fede | 2007-03-12 07:29:20 | [diff] [blame] | 2841 | ................................................ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2842 | o--o--o--o--a--b <-- old head of the branch |
| 2843 | \ |
| 2844 | o--o--o <-- new head of the branch |
Junio C Hamano | c51fede | 2007-03-12 07:29:20 | [diff] [blame] | 2845 | ................................................ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2846 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 2847 | In this case, `git fetch` will fail, and print out a warning. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2848 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 2849 | In that case, you can still force Git to update to the new head, as |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2850 | described in the following section. However, note that in the |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 2851 | situation above this may mean losing the commits labeled `a` and `b`, |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2852 | unless you've already created a reference of your own pointing to |
| 2853 | them. |
| 2854 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 2855 | [[forcing-fetch]] |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 2856 | Forcing git fetch to do non-fast-forward updates |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2857 | ------------------------------------------------ |
| 2858 | |
| 2859 | If git fetch fails because the new head of a branch is not a |
| 2860 | descendant of the old head, you may force the update with: |
| 2861 | |
| 2862 | ------------------------------------------------- |
| 2863 | $ git fetch git://example.com/proj.git +master:refs/remotes/example/master |
| 2864 | ------------------------------------------------- |
| 2865 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 2866 | Note the addition of the `+` sign. Alternatively, you can use the `-f` |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 2867 | flag to force updates of all the fetched branches, as in: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2868 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 2869 | ------------------------------------------------- |
| 2870 | $ git fetch -f origin |
| 2871 | ------------------------------------------------- |
| 2872 | |
| 2873 | Be aware that commits that the old version of example/master pointed at |
| 2874 | may be lost, as we saw in the previous section. |
| 2875 | |
| 2876 | [[remote-branch-configuration]] |
Junio C Hamano | 97bcb48 | 2010-11-25 03:16:07 | [diff] [blame] | 2877 | Configuring remote-tracking branches |
| 2878 | ------------------------------------ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2879 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 2880 | We saw above that `origin` is just a shortcut to refer to the |
Junio C Hamano | db911ee | 2007-02-28 08:13:52 | [diff] [blame] | 2881 | repository that you originally cloned from. This information is |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 2882 | stored in Git configuration variables, which you can see using |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 2883 | linkgit:git-config[1]: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2884 | |
| 2885 | ------------------------------------------------- |
| 2886 | $ git config -l |
| 2887 | core.repositoryformatversion=0 |
| 2888 | core.filemode=true |
| 2889 | core.logallrefupdates=true |
| 2890 | remote.origin.url=git://git.kernel.org/pub/scm/git/git.git |
| 2891 | remote.origin.fetch=+refs/heads/*:refs/remotes/origin/* |
| 2892 | branch.master.remote=origin |
| 2893 | branch.master.merge=refs/heads/master |
| 2894 | ------------------------------------------------- |
| 2895 | |
| 2896 | If there are other repositories that you also use frequently, you can |
| 2897 | create similar configuration options to save typing; for example, |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2898 | |
| 2899 | ------------------------------------------------- |
Junio C Hamano | 2da4ac4 | 2013-02-19 00:41:17 | [diff] [blame] | 2900 | $ git remote add example git://example.com/proj.git |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2901 | ------------------------------------------------- |
| 2902 | |
Junio C Hamano | 2da4ac4 | 2013-02-19 00:41:17 | [diff] [blame] | 2903 | adds the following to `.git/config`: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2904 | |
| 2905 | ------------------------------------------------- |
Junio C Hamano | 2da4ac4 | 2013-02-19 00:41:17 | [diff] [blame] | 2906 | [remote "example"] |
| 2907 | url = git://example.com/proj.git |
| 2908 | fetch = +refs/heads/*:refs/remotes/example/* |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2909 | ------------------------------------------------- |
| 2910 | |
Junio C Hamano | 2da4ac4 | 2013-02-19 00:41:17 | [diff] [blame] | 2911 | Also note that the above configuration can be performed by directly |
| 2912 | editing the file `.git/config` instead of using linkgit:git-remote[1]. |
| 2913 | |
| 2914 | After configuring the remote, the following three commands will do the |
| 2915 | same thing: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2916 | |
| 2917 | ------------------------------------------------- |
Junio C Hamano | 2da4ac4 | 2013-02-19 00:41:17 | [diff] [blame] | 2918 | $ git fetch git://example.com/proj.git +refs/heads/*:refs/remotes/example/* |
| 2919 | $ git fetch example +refs/heads/*:refs/remotes/example/* |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2920 | $ git fetch example |
| 2921 | ------------------------------------------------- |
| 2922 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 2923 | See linkgit:git-config[1] for more details on the configuration |
Junio C Hamano | 2da4ac4 | 2013-02-19 00:41:17 | [diff] [blame] | 2924 | options mentioned above and linkgit:git-fetch[1] for more details on |
| 2925 | the refspec syntax. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2926 | |
| 2927 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 2928 | [[git-concepts]] |
| 2929 | Git concepts |
| 2930 | ============ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2931 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 2932 | Git is built on a small number of simple but powerful ideas. While it |
| 2933 | is possible to get things done without understanding them, you will find |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 2934 | Git much more intuitive if you do. |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 2935 | |
| 2936 | We start with the most important, the <<def_object_database,object |
| 2937 | database>> and the <<def_index,index>>. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2938 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 2939 | [[the-object-database]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2940 | The Object Database |
| 2941 | ------------------- |
| 2942 | |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2943 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 2944 | We already saw in <<understanding-commits>> that all commits are stored |
| 2945 | under a 40-digit "object name". In fact, all the information needed to |
| 2946 | represent the history of a project is stored in objects with such names. |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 2947 | In each case the name is calculated by taking the SHA-1 hash of the |
| 2948 | contents of the object. The SHA-1 hash is a cryptographic hash function. |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 2949 | What that means to us is that it is impossible to find two different |
| 2950 | objects with the same name. This has a number of advantages; among |
| 2951 | others: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2952 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 2953 | - Git can quickly determine whether two objects are identical or not, |
| 2954 | just by comparing names. |
Junio C Hamano | 764a667 | 2007-10-23 01:23:31 | [diff] [blame] | 2955 | - Since object names are computed the same way in every repository, the |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 2956 | same content stored in two repositories will always be stored under |
| 2957 | the same name. |
| 2958 | - Git can detect errors when it reads an object, by checking that the |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 2959 | object's name is still the SHA-1 hash of its contents. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2960 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 2961 | (See <<object-details>> for the details of the object formatting and |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 2962 | SHA-1 calculation.) |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2963 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 2964 | There are four different types of objects: "blob", "tree", "commit", and |
| 2965 | "tag". |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2966 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 2967 | - A <<def_blob_object,"blob" object>> is used to store file data. |
Junio C Hamano | d32738e | 2008-07-09 19:53:42 | [diff] [blame] | 2968 | - A <<def_tree_object,"tree" object>> ties one or more |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 2969 | "blob" objects into a directory structure. In addition, a tree object |
| 2970 | can refer to other tree objects, thus creating a directory hierarchy. |
| 2971 | - A <<def_commit_object,"commit" object>> ties such directory hierarchies |
Junio C Hamano | 764a667 | 2007-10-23 01:23:31 | [diff] [blame] | 2972 | together into a <<def_DAG,directed acyclic graph>> of revisions--each |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 2973 | commit contains the object name of exactly one tree designating the |
| 2974 | directory hierarchy at the time of the commit. In addition, a commit |
| 2975 | refers to "parent" commit objects that describe the history of how we |
| 2976 | arrived at that directory hierarchy. |
| 2977 | - A <<def_tag_object,"tag" object>> symbolically identifies and can be |
| 2978 | used to sign other objects. It contains the object name and type of |
| 2979 | another object, a symbolic name (of course!) and, optionally, a |
| 2980 | signature. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2981 | |
| 2982 | The object types in some more detail: |
| 2983 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 2984 | [[commit-object]] |
| 2985 | Commit Object |
| 2986 | ~~~~~~~~~~~~~ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2987 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 2988 | The "commit" object links a physical state of a tree with a description |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 2989 | of how we got there and why. Use the `--pretty=raw` option to |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 2990 | linkgit:git-show[1] or linkgit:git-log[1] to examine your favorite |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 2991 | commit: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 2992 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 2993 | ------------------------------------------------ |
| 2994 | $ git show -s --pretty=raw 2be7fcb476 |
| 2995 | commit 2be7fcb4764f2dbcee52635b91fedb1b3dcf7ab4 |
| 2996 | tree fb3a8bdd0ceddd019615af4d57a53f43d8cee2bf |
| 2997 | parent 257a84d9d02e90447b149af58b271c19405edb6a |
| 2998 | author Dave Watson <dwatson@mimvista.com> 1187576872 -0400 |
| 2999 | committer Junio C Hamano <gitster@pobox.com> 1187591163 -0700 |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3000 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3001 | Fix misspelling of 'suppress' in docs |
| 3002 | |
| 3003 | Signed-off-by: Junio C Hamano <gitster@pobox.com> |
| 3004 | ------------------------------------------------ |
| 3005 | |
| 3006 | As you can see, a commit is defined by: |
| 3007 | |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 3008 | - a tree: The SHA-1 name of a tree object (as defined below), representing |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3009 | the contents of a directory at a certain point in time. |
Junio C Hamano | 44dcd49 | 2012-07-24 04:35:38 | [diff] [blame] | 3010 | - parent(s): The SHA-1 name(s) of some number of commits which represent the |
Junio C Hamano | 878cc1e | 2007-12-14 08:35:13 | [diff] [blame] | 3011 | immediately previous step(s) in the history of the project. The |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3012 | example above has one parent; merge commits may have more than |
| 3013 | one. A commit with no parents is called a "root" commit, and |
| 3014 | represents the initial revision of a project. Each project must have |
| 3015 | at least one root. A project can also have multiple roots, though |
| 3016 | that isn't common (or necessarily a good idea). |
| 3017 | - an author: The name of the person responsible for this change, together |
| 3018 | with its date. |
| 3019 | - a committer: The name of the person who actually created the commit, |
| 3020 | with the date it was done. This may be different from the author, for |
| 3021 | example, if the author was someone who wrote a patch and emailed it |
| 3022 | to the person who used it to create the commit. |
| 3023 | - a comment describing this commit. |
| 3024 | |
| 3025 | Note that a commit does not itself contain any information about what |
| 3026 | actually changed; all changes are calculated by comparing the contents |
| 3027 | of the tree referred to by this commit with the trees associated with |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 3028 | its parents. In particular, Git does not attempt to record file renames |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3029 | explicitly, though it can identify cases where the existence of the same |
| 3030 | file data at changing paths suggests a rename. (See, for example, the |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 3031 | `-M` option to linkgit:git-diff[1]). |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3032 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 3033 | A commit is usually created by linkgit:git-commit[1], which creates a |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3034 | commit whose parent is normally the current HEAD, and whose tree is |
| 3035 | taken from the content currently stored in the index. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3036 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 3037 | [[tree-object]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3038 | Tree Object |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3039 | ~~~~~~~~~~~ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3040 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 3041 | The ever-versatile linkgit:git-show[1] command can also be used to |
| 3042 | examine tree objects, but linkgit:git-ls-tree[1] will give you more |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3043 | details: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3044 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3045 | ------------------------------------------------ |
| 3046 | $ git ls-tree fb3a8bdd0ce |
| 3047 | 100644 blob 63c918c667fa005ff12ad89437f2fdc80926e21c .gitignore |
| 3048 | 100644 blob 5529b198e8d14decbe4ad99db3f7fb632de0439d .mailmap |
| 3049 | 100644 blob 6ff87c4664981e4397625791c8ea3bbb5f2279a3 COPYING |
| 3050 | 040000 tree 2fb783e477100ce076f6bf57e4a6f026013dc745 Documentation |
| 3051 | 100755 blob 3c0032cec592a765692234f1cba47dfdcc3a9200 GIT-VERSION-GEN |
| 3052 | 100644 blob 289b046a443c0647624607d471289b2c7dcd470b INSTALL |
| 3053 | 100644 blob 4eb463797adc693dc168b926b6932ff53f17d0b1 Makefile |
| 3054 | 100644 blob 548142c327a6790ff8821d67c2ee1eff7a656b52 README |
| 3055 | ... |
| 3056 | ------------------------------------------------ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3057 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3058 | As you can see, a tree object contains a list of entries, each with a |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 3059 | mode, object type, SHA-1 name, and name, sorted by name. It represents |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3060 | the contents of a single directory tree. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3061 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3062 | The object type may be a blob, representing the contents of a file, or |
| 3063 | another tree, representing the contents of a subdirectory. Since trees |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 3064 | and blobs, like all other objects, are named by the SHA-1 hash of their |
| 3065 | contents, two trees have the same SHA-1 name if and only if their |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3066 | contents (including, recursively, the contents of all subdirectories) |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 3067 | are identical. This allows Git to quickly determine the differences |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3068 | between two related tree objects, since it can ignore any entries with |
| 3069 | identical object names. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3070 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3071 | (Note: in the presence of submodules, trees may also have commits as |
Junio C Hamano | 4fd58d4 | 2007-09-30 00:51:14 | [diff] [blame] | 3072 | entries. See <<submodules>> for documentation.) |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3073 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 3074 | Note that the files all have mode 644 or 755: Git actually only pays |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3075 | attention to the executable bit. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3076 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3077 | [[blob-object]] |
| 3078 | Blob Object |
| 3079 | ~~~~~~~~~~~ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3080 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 3081 | You can use linkgit:git-show[1] to examine the contents of a blob; take, |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 3082 | for example, the blob in the entry for `COPYING` from the tree above: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3083 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3084 | ------------------------------------------------ |
| 3085 | $ git show 6ff87c4664 |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3086 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3087 | Note that the only valid version of the GPL as far as this project |
| 3088 | is concerned is _this_ particular version of the license (ie v2, not |
| 3089 | v2.2 or v3.x or whatever), unless explicitly otherwise stated. |
| 3090 | ... |
| 3091 | ------------------------------------------------ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3092 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3093 | A "blob" object is nothing but a binary blob of data. It doesn't refer |
| 3094 | to anything else or have attributes of any kind. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3095 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3096 | Since the blob is entirely defined by its data, if two files in a |
| 3097 | directory tree (or in multiple different versions of the repository) |
| 3098 | have the same contents, they will share the same blob object. The object |
| 3099 | is totally independent of its location in the directory tree, and |
| 3100 | renaming a file does not change the object that file is associated with. |
| 3101 | |
| 3102 | Note that any tree or blob object can be examined using |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 3103 | linkgit:git-show[1] with the <revision>:<path> syntax. This can |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3104 | sometimes be useful for browsing the contents of a tree that is not |
| 3105 | currently checked out. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3106 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 3107 | [[trust]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3108 | Trust |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3109 | ~~~~~ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3110 | |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 3111 | If you receive the SHA-1 name of a blob from one source, and its contents |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3112 | from another (possibly untrusted) source, you can still trust that those |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 3113 | contents are correct as long as the SHA-1 name agrees. This is because |
| 3114 | the SHA-1 is designed so that it is infeasible to find different contents |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3115 | that produce the same hash. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3116 | |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 3117 | Similarly, you need only trust the SHA-1 name of a top-level tree object |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3118 | to trust the contents of the entire directory that it refers to, and if |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 3119 | you receive the SHA-1 name of a commit from a trusted source, then you |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3120 | can easily verify the entire history of commits reachable through |
| 3121 | parents of that commit, and all of those contents of the trees referred |
| 3122 | to by those commits. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3123 | |
| 3124 | So to introduce some real trust in the system, the only thing you need |
| 3125 | to do is to digitally sign just 'one' special note, which includes the |
| 3126 | name of a top-level commit. Your digital signature shows others |
| 3127 | that you trust that commit, and the immutability of the history of |
| 3128 | commits tells others that they can trust the whole history. |
| 3129 | |
| 3130 | In other words, you can easily validate a whole archive by just |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 3131 | sending out a single email that tells the people the name (SHA-1 hash) |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3132 | of the top commit, and digitally sign that email using something |
| 3133 | like GPG/PGP. |
| 3134 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 3135 | To assist in this, Git also provides the tag object... |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3136 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 3137 | [[tag-object]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3138 | Tag Object |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3139 | ~~~~~~~~~~ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3140 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3141 | A tag object contains an object, object type, tag name, the name of the |
| 3142 | person ("tagger") who created the tag, and a message, which may contain |
Junio C Hamano | d32738e | 2008-07-09 19:53:42 | [diff] [blame] | 3143 | a signature, as can be seen using linkgit:git-cat-file[1]: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3144 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3145 | ------------------------------------------------ |
| 3146 | $ git cat-file tag v1.5.0 |
| 3147 | object 437b1b20df4b356c9342dac8d38849f24ef44f27 |
| 3148 | type commit |
| 3149 | tag v1.5.0 |
| 3150 | tagger Junio C Hamano <junkio@cox.net> 1171411200 +0000 |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3151 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3152 | GIT 1.5.0 |
| 3153 | -----BEGIN PGP SIGNATURE----- |
| 3154 | Version: GnuPG v1.4.6 (GNU/Linux) |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3155 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3156 | iD8DBQBF0lGqwMbZpPMRm5oRAuRiAJ9ohBLd7s2kqjkKlq1qqC57SbnmzQCdG4ui |
| 3157 | nLE/L9aUXdWeTFPron96DLA= |
| 3158 | =2E+0 |
| 3159 | -----END PGP SIGNATURE----- |
| 3160 | ------------------------------------------------ |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3161 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 3162 | See the linkgit:git-tag[1] command to learn how to create and verify tag |
| 3163 | objects. (Note that linkgit:git-tag[1] can also be used to create |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3164 | "lightweight tags", which are not tag objects at all, but just simple |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 3165 | references whose names begin with `refs/tags/`). |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3166 | |
| 3167 | [[pack-files]] |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 3168 | How Git stores objects efficiently: pack files |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3169 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 3170 | |
| 3171 | Newly created objects are initially created in a file named after the |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 3172 | object's SHA-1 hash (stored in `.git/objects`). |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3173 | |
| 3174 | Unfortunately this system becomes inefficient once a project has a |
| 3175 | lot of objects. Try this on an old project: |
| 3176 | |
| 3177 | ------------------------------------------------ |
| 3178 | $ git count-objects |
| 3179 | 6930 objects, 47620 kilobytes |
| 3180 | ------------------------------------------------ |
| 3181 | |
| 3182 | The first number is the number of objects which are kept in |
| 3183 | individual files. The second is the amount of space taken up by |
| 3184 | those "loose" objects. |
| 3185 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 3186 | You can save space and make Git faster by moving these loose objects in |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3187 | to a "pack file", which stores a group of objects in an efficient |
| 3188 | compressed format; the details of how pack files are formatted can be |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 3189 | found in link:technical/pack-format.html[pack format]. |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3190 | |
| 3191 | To put the loose objects into a pack, just run git repack: |
| 3192 | |
| 3193 | ------------------------------------------------ |
| 3194 | $ git repack |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 3195 | Counting objects: 6020, done. |
| 3196 | Delta compression using up to 4 threads. |
| 3197 | Compressing objects: 100% (6020/6020), done. |
| 3198 | Writing objects: 100% (6020/6020), done. |
| 3199 | Total 6020 (delta 4070), reused 0 (delta 0) |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3200 | ------------------------------------------------ |
| 3201 | |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 3202 | This creates a single "pack file" in .git/objects/pack/ |
| 3203 | containing all currently unpacked objects. You can then run |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3204 | |
| 3205 | ------------------------------------------------ |
| 3206 | $ git prune |
| 3207 | ------------------------------------------------ |
| 3208 | |
| 3209 | to remove any of the "loose" objects that are now contained in the |
| 3210 | pack. This will also remove any unreferenced objects (which may be |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 3211 | created when, for example, you use `git reset` to remove a commit). |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3212 | You can verify that the loose objects are gone by looking at the |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 3213 | `.git/objects` directory or by running |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3214 | |
| 3215 | ------------------------------------------------ |
| 3216 | $ git count-objects |
| 3217 | 0 objects, 0 kilobytes |
| 3218 | ------------------------------------------------ |
| 3219 | |
| 3220 | Although the object files are gone, any commands that refer to those |
| 3221 | objects will work exactly as they did before. |
| 3222 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 3223 | The linkgit:git-gc[1] command performs packing, pruning, and more for |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3224 | you, so is normally the only high-level command you need. |
| 3225 | |
| 3226 | [[dangling-objects]] |
| 3227 | Dangling objects |
| 3228 | ~~~~~~~~~~~~~~~~ |
| 3229 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 3230 | The linkgit:git-fsck[1] command will sometimes complain about dangling |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3231 | objects. They are not a problem. |
| 3232 | |
| 3233 | The most common cause of dangling objects is that you've rebased a |
| 3234 | branch, or you have pulled from somebody else who rebased a branch--see |
| 3235 | <<cleaning-up-history>>. In that case, the old head of the original |
| 3236 | branch still exists, as does everything it pointed to. The branch |
| 3237 | pointer itself just doesn't, since you replaced it with another one. |
| 3238 | |
| 3239 | There are also other situations that cause dangling objects. For |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 3240 | example, a "dangling blob" may arise because you did a `git add` of a |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3241 | file, but then, before you actually committed it and made it part of the |
| 3242 | bigger picture, you changed something else in that file and committed |
Junio C Hamano | 764a667 | 2007-10-23 01:23:31 | [diff] [blame] | 3243 | that *updated* thing--the old state that you added originally ends up |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3244 | not being pointed to by any commit or tree, so it's now a dangling blob |
| 3245 | object. |
| 3246 | |
| 3247 | Similarly, when the "recursive" merge strategy runs, and finds that |
| 3248 | there are criss-cross merges and thus more than one merge base (which is |
| 3249 | fairly unusual, but it does happen), it will generate one temporary |
| 3250 | midway tree (or possibly even more, if you had lots of criss-crossing |
| 3251 | merges and more than two merge bases) as a temporary internal merge |
| 3252 | base, and again, those are real objects, but the end result will not end |
| 3253 | up pointing to them, so they end up "dangling" in your repository. |
| 3254 | |
| 3255 | Generally, dangling objects aren't anything to worry about. They can |
| 3256 | even be very useful: if you screw something up, the dangling objects can |
| 3257 | be how you recover your old tree (say, you did a rebase, and realized |
Junio C Hamano | 764a667 | 2007-10-23 01:23:31 | [diff] [blame] | 3258 | that you really didn't want to--you can look at what dangling objects |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3259 | you have, and decide to reset your head to some old dangling state). |
| 3260 | |
| 3261 | For commits, you can just use: |
| 3262 | |
| 3263 | ------------------------------------------------ |
| 3264 | $ gitk <dangling-commit-sha-goes-here> --not --all |
| 3265 | ------------------------------------------------ |
| 3266 | |
| 3267 | This asks for all the history reachable from the given commit but not |
| 3268 | from any branch, tag, or other reference. If you decide it's something |
| 3269 | you want, you can always create a new reference to it, e.g., |
| 3270 | |
| 3271 | ------------------------------------------------ |
| 3272 | $ git branch recovered-branch <dangling-commit-sha-goes-here> |
| 3273 | ------------------------------------------------ |
| 3274 | |
| 3275 | For blobs and trees, you can't do the same, but you can still examine |
| 3276 | them. You can just do |
| 3277 | |
| 3278 | ------------------------------------------------ |
| 3279 | $ git show <dangling-blob/tree-sha-goes-here> |
| 3280 | ------------------------------------------------ |
| 3281 | |
| 3282 | to show what the contents of the blob were (or, for a tree, basically |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 3283 | what the `ls` for that directory was), and that may give you some idea |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3284 | of what the operation was that left that dangling object. |
| 3285 | |
| 3286 | Usually, dangling blobs and trees aren't very interesting. They're |
| 3287 | almost always the result of either being a half-way mergebase (the blob |
| 3288 | will often even have the conflict markers from a merge in it, if you |
| 3289 | have had conflicting merges that you fixed up by hand), or simply |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 3290 | because you interrupted a `git fetch` with ^C or something like that, |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3291 | leaving _some_ of the new objects in the object database, but just |
| 3292 | dangling and useless. |
| 3293 | |
| 3294 | Anyway, once you are sure that you're not interested in any dangling |
| 3295 | state, you can just prune all unreachable objects: |
| 3296 | |
| 3297 | ------------------------------------------------ |
| 3298 | $ git prune |
| 3299 | ------------------------------------------------ |
| 3300 | |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 3301 | and they'll be gone. (You should only run `git prune` on a quiescent |
Junio C Hamano | 764a667 | 2007-10-23 01:23:31 | [diff] [blame] | 3302 | repository--it's kind of like doing a filesystem fsck recovery: you |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3303 | don't want to do that while the filesystem is mounted. |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 3304 | `git prune` is designed not to cause any harm in such cases of concurrent |
| 3305 | accesses to a repository but you might receive confusing or scary messages.) |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3306 | |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 3307 | [[recovering-from-repository-corruption]] |
| 3308 | Recovering from repository corruption |
| 3309 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 3310 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 3311 | By design, Git treats data trusted to it with caution. However, even in |
| 3312 | the absence of bugs in Git itself, it is still possible that hardware or |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 3313 | operating system errors could corrupt data. |
| 3314 | |
| 3315 | The first defense against such problems is backups. You can back up a |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 3316 | Git directory using clone, or just using cp, tar, or any other backup |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 3317 | mechanism. |
| 3318 | |
| 3319 | As a last resort, you can search for the corrupted objects and attempt |
| 3320 | to replace them by hand. Back up your repository before attempting this |
| 3321 | in case you corrupt things even more in the process. |
| 3322 | |
| 3323 | We'll assume that the problem is a single missing or corrupted blob, |
Junio C Hamano | 878cc1e | 2007-12-14 08:35:13 | [diff] [blame] | 3324 | which is sometimes a solvable problem. (Recovering missing trees and |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 3325 | especially commits is *much* harder). |
| 3326 | |
| 3327 | Before starting, verify that there is corruption, and figure out where |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 3328 | it is with linkgit:git-fsck[1]; this may be time-consuming. |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 3329 | |
| 3330 | Assume the output looks like this: |
| 3331 | |
| 3332 | ------------------------------------------------ |
Junio C Hamano | 81d540a | 2012-03-02 19:52:47 | [diff] [blame] | 3333 | $ git fsck --full --no-dangling |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 3334 | broken link from tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8 |
| 3335 | to blob 4b9458b3786228369c63936db65827de3cc06200 |
| 3336 | missing blob 4b9458b3786228369c63936db65827de3cc06200 |
| 3337 | ------------------------------------------------ |
| 3338 | |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 3339 | Now you know that blob 4b9458b3 is missing, and that the tree 2d9263c6 |
| 3340 | points to it. If you could find just one copy of that missing blob |
| 3341 | object, possibly in some other repository, you could move it into |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 3342 | `.git/objects/4b/9458b3...` and be done. Suppose you can't. You can |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 3343 | still examine the tree that pointed to it with linkgit:git-ls-tree[1], |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 3344 | which might output something like: |
| 3345 | |
| 3346 | ------------------------------------------------ |
| 3347 | $ git ls-tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8 |
| 3348 | 100644 blob 8d14531846b95bfa3564b58ccfb7913a034323b8 .gitignore |
| 3349 | 100644 blob ebf9bf84da0aab5ed944264a5db2a65fe3a3e883 .mailmap |
| 3350 | 100644 blob ca442d313d86dc67e0a2e5d584b465bd382cbf5c COPYING |
| 3351 | ... |
| 3352 | 100644 blob 4b9458b3786228369c63936db65827de3cc06200 myfile |
| 3353 | ... |
| 3354 | ------------------------------------------------ |
| 3355 | |
| 3356 | So now you know that the missing blob was the data for a file named |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 3357 | `myfile`. And chances are you can also identify the directory--let's |
| 3358 | say it's in `somedirectory`. If you're lucky the missing copy might be |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 3359 | the same as the copy you have checked out in your working tree at |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 3360 | `somedirectory/myfile`; you can test whether that's right with |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 3361 | linkgit:git-hash-object[1]: |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 3362 | |
| 3363 | ------------------------------------------------ |
| 3364 | $ git hash-object -w somedirectory/myfile |
| 3365 | ------------------------------------------------ |
| 3366 | |
| 3367 | which will create and store a blob object with the contents of |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 3368 | somedirectory/myfile, and output the SHA-1 of that object. if you're |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 3369 | extremely lucky it might be 4b9458b3786228369c63936db65827de3cc06200, in |
| 3370 | which case you've guessed right, and the corruption is fixed! |
| 3371 | |
| 3372 | Otherwise, you need more information. How do you tell which version of |
| 3373 | the file has been lost? |
| 3374 | |
| 3375 | The easiest way to do this is with: |
| 3376 | |
| 3377 | ------------------------------------------------ |
| 3378 | $ git log --raw --all --full-history -- somedirectory/myfile |
| 3379 | ------------------------------------------------ |
| 3380 | |
| 3381 | Because you're asking for raw output, you'll now get something like |
| 3382 | |
| 3383 | ------------------------------------------------ |
| 3384 | commit abc |
| 3385 | Author: |
| 3386 | Date: |
| 3387 | ... |
| 3388 | :100644 100644 4b9458b... newsha... M somedirectory/myfile |
| 3389 | |
| 3390 | |
| 3391 | commit xyz |
| 3392 | Author: |
| 3393 | Date: |
| 3394 | |
| 3395 | ... |
| 3396 | :100644 100644 oldsha... 4b9458b... M somedirectory/myfile |
| 3397 | ------------------------------------------------ |
| 3398 | |
Junio C Hamano | 44dcd49 | 2012-07-24 04:35:38 | [diff] [blame] | 3399 | This tells you that the immediately following version of the file was |
| 3400 | "newsha", and that the immediately preceding version was "oldsha". |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 3401 | You also know the commit messages that went with the change from oldsha |
| 3402 | to 4b9458b and with the change from 4b9458b to newsha. |
| 3403 | |
| 3404 | If you've been committing small enough changes, you may now have a good |
| 3405 | shot at reconstructing the contents of the in-between state 4b9458b. |
| 3406 | |
| 3407 | If you can do that, you can now recreate the missing object with |
| 3408 | |
| 3409 | ------------------------------------------------ |
| 3410 | $ git hash-object -w <recreated-file> |
| 3411 | ------------------------------------------------ |
| 3412 | |
| 3413 | and your repository is good again! |
| 3414 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 3415 | (Btw, you could have ignored the `fsck`, and started with doing a |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 3416 | |
| 3417 | ------------------------------------------------ |
| 3418 | $ git log --raw --all |
| 3419 | ------------------------------------------------ |
| 3420 | |
| 3421 | and just looked for the sha of the missing object (4b9458b..) in that |
Junio C Hamano | 8c5696d | 2013-02-11 05:35:00 | [diff] [blame] | 3422 | whole thing. It's up to you--Git does *have* a lot of information, it is |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 3423 | just missing one particular blob version. |
| 3424 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 3425 | [[the-index]] |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3426 | The index |
Junio C Hamano | 1f7c4a5 | 2015-10-14 22:15:51 | [diff] [blame] | 3427 | --------- |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3428 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 3429 | The index is a binary file (generally kept in `.git/index`) containing a |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 3430 | sorted list of path names, each with permissions and the SHA-1 of a blob |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 3431 | object; linkgit:git-ls-files[1] can show you the contents of the index: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3432 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3433 | ------------------------------------------------- |
| 3434 | $ git ls-files --stage |
| 3435 | 100644 63c918c667fa005ff12ad89437f2fdc80926e21c 0 .gitignore |
| 3436 | 100644 5529b198e8d14decbe4ad99db3f7fb632de0439d 0 .mailmap |
| 3437 | 100644 6ff87c4664981e4397625791c8ea3bbb5f2279a3 0 COPYING |
| 3438 | 100644 a37b2152bd26be2c2289e1f57a292534a51a93c7 0 Documentation/.gitignore |
| 3439 | 100644 fbefe9a45b00a54b58d94d06eca48b03d40a50e0 0 Documentation/Makefile |
| 3440 | ... |
| 3441 | 100644 2511aef8d89ab52be5ec6a5e46236b4b6bcd07ea 0 xdiff/xtypes.h |
| 3442 | 100644 2ade97b2574a9f77e7ae4002a4e07a6a38e46d07 0 xdiff/xutils.c |
| 3443 | 100644 d5de8292e05e7c36c4b68857c1cf9855e3d2f70a 0 xdiff/xutils.h |
| 3444 | ------------------------------------------------- |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3445 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3446 | Note that in older documentation you may see the index called the |
| 3447 | "current directory cache" or just the "cache". It has three important |
| 3448 | properties: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3449 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3450 | 1. The index contains all the information necessary to generate a single |
| 3451 | (uniquely determined) tree object. |
| 3452 | + |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 3453 | For example, running linkgit:git-commit[1] generates this tree object |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3454 | from the index, stores it in the object database, and uses it as the |
| 3455 | tree object associated with the new commit. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3456 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3457 | 2. The index enables fast comparisons between the tree object it defines |
| 3458 | and the working tree. |
| 3459 | + |
| 3460 | It does this by storing some additional data for each entry (such as |
| 3461 | the last modified time). This data is not displayed above, and is not |
| 3462 | stored in the created tree object, but it can be used to determine |
| 3463 | quickly which files in the working directory differ from what was |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 3464 | stored in the index, and thus save Git from having to read all of the |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3465 | data from such files to look for changes. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3466 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3467 | 3. It can efficiently represent information about merge conflicts |
| 3468 | between different tree objects, allowing each pathname to be |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3469 | associated with sufficient information about the trees involved that |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3470 | you can create a three-way merge between them. |
| 3471 | + |
| 3472 | We saw in <<conflict-resolution>> that during a merge the index can |
| 3473 | store multiple versions of a single file (called "stages"). The third |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 3474 | column in the linkgit:git-ls-files[1] output above is the stage |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3475 | number, and will take on values other than 0 for files with merge |
| 3476 | conflicts. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3477 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3478 | The index is thus a sort of temporary staging area, which is filled with |
| 3479 | a tree which you are in the process of working on. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3480 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3481 | If you blow the index away entirely, you generally haven't lost any |
| 3482 | information as long as you have the name of the tree that it described. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3483 | |
Junio C Hamano | 9810d63 | 2007-09-24 01:05:34 | [diff] [blame] | 3484 | [[submodules]] |
| 3485 | Submodules |
| 3486 | ========== |
| 3487 | |
Junio C Hamano | 4fd58d4 | 2007-09-30 00:51:14 | [diff] [blame] | 3488 | Large projects are often composed of smaller, self-contained modules. For |
| 3489 | example, an embedded Linux distribution's source tree would include every |
| 3490 | piece of software in the distribution with some local modifications; a movie |
| 3491 | player might need to build against a specific, known-working version of a |
| 3492 | decompression library; several independent programs might all share the same |
| 3493 | build scripts. |
Junio C Hamano | 9810d63 | 2007-09-24 01:05:34 | [diff] [blame] | 3494 | |
Junio C Hamano | 4fd58d4 | 2007-09-30 00:51:14 | [diff] [blame] | 3495 | With centralized revision control systems this is often accomplished by |
| 3496 | including every module in one single repository. Developers can check out |
| 3497 | all modules or only the modules they need to work with. They can even modify |
| 3498 | files across several modules in a single commit while moving things around |
| 3499 | or updating APIs and translations. |
| 3500 | |
| 3501 | Git does not allow partial checkouts, so duplicating this approach in Git |
| 3502 | would force developers to keep a local copy of modules they are not |
| 3503 | interested in touching. Commits in an enormous checkout would be slower |
| 3504 | than you'd expect as Git would have to scan every directory for changes. |
| 3505 | If modules have a lot of local history, clones would take forever. |
| 3506 | |
| 3507 | On the plus side, distributed revision control systems can much better |
| 3508 | integrate with external sources. In a centralized model, a single arbitrary |
| 3509 | snapshot of the external project is exported from its own revision control |
| 3510 | and then imported into the local revision control on a vendor branch. All |
| 3511 | the history is hidden. With distributed revision control you can clone the |
| 3512 | entire external history and much more easily follow development and re-merge |
| 3513 | local changes. |
| 3514 | |
| 3515 | Git's submodule support allows a repository to contain, as a subdirectory, a |
| 3516 | checkout of an external project. Submodules maintain their own identity; |
| 3517 | the submodule support just stores the submodule repository location and |
| 3518 | commit ID, so other developers who clone the containing project |
| 3519 | ("superproject") can easily clone all the submodules at the same revision. |
| 3520 | Partial checkouts of the superproject are possible: you can tell Git to |
| 3521 | clone none, some or all of the submodules. |
| 3522 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 3523 | The linkgit:git-submodule[1] command is available since Git 1.5.3. Users |
Junio C Hamano | 4fd58d4 | 2007-09-30 00:51:14 | [diff] [blame] | 3524 | with Git 1.5.2 can look up the submodule commits in the repository and |
| 3525 | manually check them out; earlier versions won't recognize the submodules at |
| 3526 | all. |
Junio C Hamano | 9810d63 | 2007-09-24 01:05:34 | [diff] [blame] | 3527 | |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 3528 | To see how submodule support works, create four example |
Junio C Hamano | 9810d63 | 2007-09-24 01:05:34 | [diff] [blame] | 3529 | repositories that can be used later as a submodule: |
| 3530 | |
| 3531 | ------------------------------------------------- |
| 3532 | $ mkdir ~/git |
| 3533 | $ cd ~/git |
| 3534 | $ for i in a b c d |
| 3535 | do |
| 3536 | mkdir $i |
| 3537 | cd $i |
| 3538 | git init |
| 3539 | echo "module $i" > $i.txt |
| 3540 | git add $i.txt |
| 3541 | git commit -m "Initial commit, submodule $i" |
| 3542 | cd .. |
| 3543 | done |
| 3544 | ------------------------------------------------- |
| 3545 | |
| 3546 | Now create the superproject and add all the submodules: |
| 3547 | |
| 3548 | ------------------------------------------------- |
| 3549 | $ mkdir super |
| 3550 | $ cd super |
| 3551 | $ git init |
| 3552 | $ for i in a b c d |
| 3553 | do |
Junio C Hamano | 7f80ae8 | 2008-07-30 18:31:35 | [diff] [blame] | 3554 | git submodule add ~/git/$i $i |
Junio C Hamano | 9810d63 | 2007-09-24 01:05:34 | [diff] [blame] | 3555 | done |
| 3556 | ------------------------------------------------- |
| 3557 | |
| 3558 | NOTE: Do not use local URLs here if you plan to publish your superproject! |
| 3559 | |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 3560 | See what files `git submodule` created: |
Junio C Hamano | 9810d63 | 2007-09-24 01:05:34 | [diff] [blame] | 3561 | |
| 3562 | ------------------------------------------------- |
| 3563 | $ ls -a |
| 3564 | . .. .git .gitmodules a b c d |
| 3565 | ------------------------------------------------- |
| 3566 | |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 3567 | The `git submodule add <repo> <path>` command does a couple of things: |
Junio C Hamano | 9810d63 | 2007-09-24 01:05:34 | [diff] [blame] | 3568 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 3569 | - It clones the submodule from `<repo>` to the given `<path>` under the |
Junio C Hamano | 7f80ae8 | 2008-07-30 18:31:35 | [diff] [blame] | 3570 | current directory and by default checks out the master branch. |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 3571 | - It adds the submodule's clone path to the linkgit:gitmodules[5] file and |
Junio C Hamano | 4fd58d4 | 2007-09-30 00:51:14 | [diff] [blame] | 3572 | adds this file to the index, ready to be committed. |
Junio C Hamano | 9810d63 | 2007-09-24 01:05:34 | [diff] [blame] | 3573 | - It adds the submodule's current commit ID to the index, ready to be |
| 3574 | committed. |
| 3575 | |
| 3576 | Commit the superproject: |
| 3577 | |
| 3578 | ------------------------------------------------- |
| 3579 | $ git commit -m "Add submodules a, b, c and d." |
| 3580 | ------------------------------------------------- |
| 3581 | |
| 3582 | Now clone the superproject: |
| 3583 | |
| 3584 | ------------------------------------------------- |
| 3585 | $ cd .. |
| 3586 | $ git clone super cloned |
| 3587 | $ cd cloned |
| 3588 | ------------------------------------------------- |
| 3589 | |
| 3590 | The submodule directories are there, but they're empty: |
| 3591 | |
| 3592 | ------------------------------------------------- |
| 3593 | $ ls -a a |
| 3594 | . .. |
| 3595 | $ git submodule status |
| 3596 | -d266b9873ad50488163457f025db7cdd9683d88b a |
| 3597 | -e81d457da15309b4fef4249aba9b50187999670d b |
| 3598 | -c1536a972b9affea0f16e0680ba87332dc059146 c |
| 3599 | -d96249ff5d57de5de093e6baff9e0aafa5276a74 d |
| 3600 | ------------------------------------------------- |
| 3601 | |
| 3602 | NOTE: The commit object names shown above would be different for you, but they |
| 3603 | should match the HEAD commit object names of your repositories. You can check |
| 3604 | it by running `git ls-remote ../a`. |
| 3605 | |
| 3606 | Pulling down the submodules is a two-step process. First run `git submodule |
| 3607 | init` to add the submodule repository URLs to `.git/config`: |
| 3608 | |
| 3609 | ------------------------------------------------- |
| 3610 | $ git submodule init |
| 3611 | ------------------------------------------------- |
| 3612 | |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 3613 | Now use `git submodule update` to clone the repositories and check out the |
Junio C Hamano | 9810d63 | 2007-09-24 01:05:34 | [diff] [blame] | 3614 | commits specified in the superproject: |
| 3615 | |
| 3616 | ------------------------------------------------- |
| 3617 | $ git submodule update |
| 3618 | $ cd a |
| 3619 | $ ls -a |
| 3620 | . .. .git a.txt |
| 3621 | ------------------------------------------------- |
| 3622 | |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 3623 | One major difference between `git submodule update` and `git submodule add` is |
| 3624 | that `git submodule update` checks out a specific commit, rather than the tip |
Junio C Hamano | 9810d63 | 2007-09-24 01:05:34 | [diff] [blame] | 3625 | of a branch. It's like checking out a tag: the head is detached, so you're not |
| 3626 | working on a branch. |
| 3627 | |
| 3628 | ------------------------------------------------- |
| 3629 | $ git branch |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 3630 | * (detached from d266b98) |
Junio C Hamano | 9810d63 | 2007-09-24 01:05:34 | [diff] [blame] | 3631 | master |
| 3632 | ------------------------------------------------- |
| 3633 | |
| 3634 | If you want to make a change within a submodule and you have a detached head, |
| 3635 | then you should create or checkout a branch, make your changes, publish the |
| 3636 | change within the submodule, and then update the superproject to reference the |
| 3637 | new commit: |
| 3638 | |
| 3639 | ------------------------------------------------- |
| 3640 | $ git checkout master |
| 3641 | ------------------------------------------------- |
| 3642 | |
| 3643 | or |
| 3644 | |
| 3645 | ------------------------------------------------- |
| 3646 | $ git checkout -b fix-up |
| 3647 | ------------------------------------------------- |
| 3648 | |
| 3649 | then |
| 3650 | |
| 3651 | ------------------------------------------------- |
| 3652 | $ echo "adding a line again" >> a.txt |
| 3653 | $ git commit -a -m "Updated the submodule from within the superproject." |
| 3654 | $ git push |
| 3655 | $ cd .. |
| 3656 | $ git diff |
| 3657 | diff --git a/a b/a |
| 3658 | index d266b98..261dfac 160000 |
| 3659 | --- a/a |
| 3660 | +++ b/a |
| 3661 | @@ -1 +1 @@ |
| 3662 | -Subproject commit d266b9873ad50488163457f025db7cdd9683d88b |
| 3663 | +Subproject commit 261dfac35cb99d380eb966e102c1197139f7fa24 |
| 3664 | $ git add a |
| 3665 | $ git commit -m "Updated submodule a." |
| 3666 | $ git push |
| 3667 | ------------------------------------------------- |
| 3668 | |
| 3669 | You have to run `git submodule update` after `git pull` if you want to update |
| 3670 | submodules, too. |
| 3671 | |
| 3672 | Pitfalls with submodules |
| 3673 | ------------------------ |
| 3674 | |
| 3675 | Always publish the submodule change before publishing the change to the |
| 3676 | superproject that references it. If you forget to publish the submodule change, |
| 3677 | others won't be able to clone the repository: |
| 3678 | |
| 3679 | ------------------------------------------------- |
| 3680 | $ cd ~/git/super/a |
| 3681 | $ echo i added another line to this file >> a.txt |
| 3682 | $ git commit -a -m "doing it wrong this time" |
| 3683 | $ cd .. |
| 3684 | $ git add a |
| 3685 | $ git commit -m "Updated submodule a again." |
| 3686 | $ git push |
| 3687 | $ cd ~/git/cloned |
| 3688 | $ git pull |
| 3689 | $ git submodule update |
| 3690 | error: pathspec '261dfac35cb99d380eb966e102c1197139f7fa24' did not match any file(s) known to git. |
| 3691 | Did you forget to 'git add'? |
| 3692 | Unable to checkout '261dfac35cb99d380eb966e102c1197139f7fa24' in submodule path 'a' |
| 3693 | ------------------------------------------------- |
| 3694 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 3695 | In older Git versions it could be easily forgotten to commit new or modified |
Junio C Hamano | 2b186d8 | 2010-02-02 07:17:34 | [diff] [blame] | 3696 | files in a submodule, which silently leads to similar problems as not pushing |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 3697 | the submodule changes. Starting with Git 1.7.0 both `git status` and `git diff` |
Junio C Hamano | 2b186d8 | 2010-02-02 07:17:34 | [diff] [blame] | 3698 | in the superproject show submodules as modified when they contain new or |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 3699 | modified files to protect against accidentally committing such a state. `git |
| 3700 | diff` will also add a `-dirty` to the work tree side when generating patch |
| 3701 | output or used with the `--submodule` option: |
Junio C Hamano | 2b186d8 | 2010-02-02 07:17:34 | [diff] [blame] | 3702 | |
| 3703 | ------------------------------------------------- |
| 3704 | $ git diff |
| 3705 | diff --git a/sub b/sub |
| 3706 | --- a/sub |
| 3707 | +++ b/sub |
| 3708 | @@ -1 +1 @@ |
| 3709 | -Subproject commit 3f356705649b5d566d97ff843cf193359229a453 |
| 3710 | +Subproject commit 3f356705649b5d566d97ff843cf193359229a453-dirty |
| 3711 | $ git diff --submodule |
| 3712 | Submodule sub 3f35670..3f35670-dirty: |
| 3713 | ------------------------------------------------- |
| 3714 | |
Junio C Hamano | 9810d63 | 2007-09-24 01:05:34 | [diff] [blame] | 3715 | You also should not rewind branches in a submodule beyond commits that were |
| 3716 | ever recorded in any superproject. |
| 3717 | |
| 3718 | It's not safe to run `git submodule update` if you've made and committed |
| 3719 | changes within a submodule without checking out a branch first. They will be |
| 3720 | silently overwritten: |
| 3721 | |
| 3722 | ------------------------------------------------- |
| 3723 | $ cat a.txt |
| 3724 | module a |
| 3725 | $ echo line added from private2 >> a.txt |
| 3726 | $ git commit -a -m "line added inside private2" |
| 3727 | $ cd .. |
| 3728 | $ git submodule update |
| 3729 | Submodule path 'a': checked out 'd266b9873ad50488163457f025db7cdd9683d88b' |
| 3730 | $ cd a |
| 3731 | $ cat a.txt |
| 3732 | module a |
| 3733 | ------------------------------------------------- |
| 3734 | |
| 3735 | NOTE: The changes are still visible in the submodule's reflog. |
| 3736 | |
Junio C Hamano | 5dab5a9 | 2013-02-25 18:51:24 | [diff] [blame] | 3737 | If you have uncommitted changes in your submodule working tree, `git |
| 3738 | submodule update` will not overwrite them. Instead, you get the usual |
| 3739 | warning about not being able switch from a dirty branch. |
Junio C Hamano | 9810d63 | 2007-09-24 01:05:34 | [diff] [blame] | 3740 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3741 | [[low-level-operations]] |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 3742 | Low-level Git operations |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3743 | ======================== |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3744 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3745 | Many of the higher-level commands were originally implemented as shell |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 3746 | scripts using a smaller core of low-level Git commands. These can still |
| 3747 | be useful when doing unusual things with Git, or just as a way to |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3748 | understand its inner workings. |
| 3749 | |
| 3750 | [[object-manipulation]] |
| 3751 | Object access and manipulation |
| 3752 | ------------------------------ |
| 3753 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 3754 | The linkgit:git-cat-file[1] command can show the contents of any object, |
| 3755 | though the higher-level linkgit:git-show[1] is usually more useful. |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3756 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 3757 | The linkgit:git-commit-tree[1] command allows constructing commits with |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3758 | arbitrary parents and trees. |
| 3759 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 3760 | A tree can be created with linkgit:git-write-tree[1] and its data can be |
| 3761 | accessed by linkgit:git-ls-tree[1]. Two trees can be compared with |
| 3762 | linkgit:git-diff-tree[1]. |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3763 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 3764 | A tag is created with linkgit:git-mktag[1], and the signature can be |
| 3765 | verified by linkgit:git-verify-tag[1], though it is normally simpler to |
| 3766 | use linkgit:git-tag[1] for both. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3767 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 3768 | [[the-workflow]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3769 | The Workflow |
| 3770 | ------------ |
| 3771 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 3772 | High-level operations such as linkgit:git-commit[1], |
| 3773 | linkgit:git-checkout[1] and linkgit:git-reset[1] work by moving data |
Junio C Hamano | 764a667 | 2007-10-23 01:23:31 | [diff] [blame] | 3774 | between the working tree, the index, and the object database. Git |
| 3775 | provides low-level operations which perform each of these steps |
| 3776 | individually. |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3777 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 3778 | Generally, all Git operations work on the index file. Some operations |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3779 | work *purely* on the index file (showing the current state of the |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3780 | index), but most operations move data between the index file and either |
| 3781 | the database or the working directory. Thus there are four main |
| 3782 | combinations: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3783 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 3784 | [[working-directory-to-index]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3785 | working directory -> index |
| 3786 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 3787 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 3788 | The linkgit:git-update-index[1] command updates the index with |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3789 | information from the working directory. You generally update the |
| 3790 | index information by just specifying the filename you want to update, |
| 3791 | like so: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3792 | |
| 3793 | ------------------------------------------------- |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3794 | $ git update-index filename |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3795 | ------------------------------------------------- |
| 3796 | |
Junio C Hamano | 826f5c4 | 2014-02-07 20:33:30 | [diff] [blame] | 3797 | but to avoid common mistakes with filename globbing etc., the command |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3798 | will not normally add totally new entries or remove old entries, |
| 3799 | i.e. it will normally just update existing cache entries. |
| 3800 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 3801 | To tell Git that yes, you really do realize that certain files no |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3802 | longer exist, or that new files should be added, you |
| 3803 | should use the `--remove` and `--add` flags respectively. |
| 3804 | |
| 3805 | NOTE! A `--remove` flag does 'not' mean that subsequent filenames will |
| 3806 | necessarily be removed: if the files still exist in your directory |
| 3807 | structure, the index will be updated with their new status, not |
Junio C Hamano | 774239c | 2007-12-01 01:57:43 | [diff] [blame] | 3808 | removed. The only thing `--remove` means is that update-index will be |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3809 | considering a removed file to be a valid thing, and if the file really |
| 3810 | does not exist any more, it will update the index accordingly. |
| 3811 | |
Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 3812 | As a special case, you can also do `git update-index --refresh`, which |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3813 | will refresh the "stat" information of each index to match the current |
| 3814 | stat information. It will 'not' update the object status itself, and |
| 3815 | it will only update the fields that are used to quickly test whether |
| 3816 | an object still matches its old backing store object. |
| 3817 | |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 3818 | The previously introduced linkgit:git-add[1] is just a wrapper for |
| 3819 | linkgit:git-update-index[1]. |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3820 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 3821 | [[index-to-object-database]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3822 | index -> object database |
| 3823 | ~~~~~~~~~~~~~~~~~~~~~~~~ |
| 3824 | |
| 3825 | You write your current index file to a "tree" object with the program |
| 3826 | |
| 3827 | ------------------------------------------------- |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 3828 | $ git write-tree |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3829 | ------------------------------------------------- |
| 3830 | |
Junio C Hamano | 764a667 | 2007-10-23 01:23:31 | [diff] [blame] | 3831 | that doesn't come with any options--it will just write out the |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3832 | current index into the set of tree objects that describe that state, |
| 3833 | and it will return the name of the resulting top-level tree. You can |
| 3834 | use that tree to re-generate the index at any time by going in the |
| 3835 | other direction: |
| 3836 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 3837 | [[object-database-to-index]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3838 | object database -> index |
| 3839 | ~~~~~~~~~~~~~~~~~~~~~~~~ |
| 3840 | |
| 3841 | You read a "tree" file from the object database, and use that to |
Junio C Hamano | 764a667 | 2007-10-23 01:23:31 | [diff] [blame] | 3842 | populate (and overwrite--don't do this if your index contains any |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3843 | unsaved state that you might want to restore later!) your current |
| 3844 | index. Normal operation is just |
| 3845 | |
| 3846 | ------------------------------------------------- |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 3847 | $ git read-tree <SHA-1 of tree> |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3848 | ------------------------------------------------- |
| 3849 | |
| 3850 | and your index file will now be equivalent to the tree that you saved |
| 3851 | earlier. However, that is only your 'index' file: your working |
| 3852 | directory contents have not been modified. |
| 3853 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 3854 | [[index-to-working-directory]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3855 | index -> working directory |
| 3856 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 3857 | |
| 3858 | You update your working directory from the index by "checking out" |
| 3859 | files. This is not a very common operation, since normally you'd just |
| 3860 | keep your files updated, and rather than write to your working |
| 3861 | directory, you'd tell the index files about the changes in your |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 3862 | working directory (i.e. `git update-index`). |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3863 | |
| 3864 | However, if you decide to jump to a new version, or check out somebody |
| 3865 | else's version, or just restore a previous tree, you'd populate your |
| 3866 | index file with read-tree, and then you need to check out the result |
| 3867 | with |
| 3868 | |
| 3869 | ------------------------------------------------- |
Junio C Hamano | fce7c7e | 2008-07-02 03:06:38 | [diff] [blame] | 3870 | $ git checkout-index filename |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3871 | ------------------------------------------------- |
| 3872 | |
| 3873 | or, if you want to check out all of the index, use `-a`. |
| 3874 | |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 3875 | NOTE! `git checkout-index` normally refuses to overwrite old files, so |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3876 | if you have an old version of the tree already checked out, you will |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 3877 | need to use the `-f` flag ('before' the `-a` flag or the filename) to |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3878 | 'force' the checkout. |
| 3879 | |
| 3880 | |
| 3881 | Finally, there are a few odds and ends which are not purely moving |
| 3882 | from one representation to the other: |
| 3883 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 3884 | [[tying-it-all-together]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3885 | Tying it all together |
| 3886 | ~~~~~~~~~~~~~~~~~~~~~ |
| 3887 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 3888 | To commit a tree you have instantiated with `git write-tree`, you'd |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3889 | create a "commit" object that refers to that tree and the history |
Junio C Hamano | 764a667 | 2007-10-23 01:23:31 | [diff] [blame] | 3890 | behind it--most notably the "parent" commits that preceded it in |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3891 | history. |
| 3892 | |
| 3893 | Normally a "commit" has one parent: the previous state of the tree |
| 3894 | before a certain change was made. However, sometimes it can have two |
| 3895 | or more parent commits, in which case we call it a "merge", due to the |
| 3896 | fact that such a commit brings together ("merges") two or more |
| 3897 | previous states represented by other commits. |
| 3898 | |
| 3899 | In other words, while a "tree" represents a particular directory state |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 3900 | of a working directory, a "commit" represents that state in time, |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3901 | and explains how we got there. |
| 3902 | |
| 3903 | You create a commit object by giving it the tree that describes the |
| 3904 | state at the time of the commit, and a list of parents: |
| 3905 | |
| 3906 | ------------------------------------------------- |
Junio C Hamano | d2179ef | 2010-10-22 04:12:17 | [diff] [blame] | 3907 | $ git commit-tree <tree> -p <parent> [(-p <parent2>)...] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3908 | ------------------------------------------------- |
| 3909 | |
| 3910 | and then giving the reason for the commit on stdin (either through |
| 3911 | redirection from a pipe or file, or by just typing it at the tty). |
| 3912 | |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 3913 | `git commit-tree` will return the name of the object that represents |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3914 | that commit, and you should save it away for later use. Normally, |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 3915 | you'd commit a new `HEAD` state, and while Git doesn't care where you |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3916 | save the note about that state, in practice we tend to just write the |
| 3917 | result to the file pointed at by `.git/HEAD`, so that we can always see |
| 3918 | what the last committed state was. |
| 3919 | |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 3920 | Here is a picture that illustrates how various pieces fit together: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3921 | |
| 3922 | ------------ |
| 3923 | |
| 3924 | commit-tree |
| 3925 | commit obj |
| 3926 | +----+ |
| 3927 | | | |
| 3928 | | | |
| 3929 | V V |
| 3930 | +-----------+ |
| 3931 | | Object DB | |
| 3932 | | Backing | |
| 3933 | | Store | |
| 3934 | +-----------+ |
| 3935 | ^ |
| 3936 | write-tree | | |
| 3937 | tree obj | | |
| 3938 | | | read-tree |
| 3939 | | | tree obj |
| 3940 | V |
| 3941 | +-----------+ |
| 3942 | | Index | |
| 3943 | | "cache" | |
| 3944 | +-----------+ |
| 3945 | update-index ^ |
| 3946 | blob obj | | |
| 3947 | | | |
| 3948 | checkout-index -u | | checkout-index |
| 3949 | stat | | blob obj |
| 3950 | V |
| 3951 | +-----------+ |
| 3952 | | Working | |
| 3953 | | Directory | |
| 3954 | +-----------+ |
| 3955 | |
| 3956 | ------------ |
| 3957 | |
| 3958 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 3959 | [[examining-the-data]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3960 | Examining the data |
| 3961 | ------------------ |
| 3962 | |
| 3963 | You can examine the data represented in the object database and the |
| 3964 | index with various helper tools. For every object, you can use |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 3965 | linkgit:git-cat-file[1] to examine details about the |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3966 | object: |
| 3967 | |
| 3968 | ------------------------------------------------- |
Junio C Hamano | fce7c7e | 2008-07-02 03:06:38 | [diff] [blame] | 3969 | $ git cat-file -t <objectname> |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3970 | ------------------------------------------------- |
| 3971 | |
| 3972 | shows the type of the object, and once you have the type (which is |
| 3973 | usually implicit in where you find the object), you can use |
| 3974 | |
| 3975 | ------------------------------------------------- |
Junio C Hamano | fce7c7e | 2008-07-02 03:06:38 | [diff] [blame] | 3976 | $ git cat-file blob|tree|commit|tag <objectname> |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3977 | ------------------------------------------------- |
| 3978 | |
| 3979 | to show its contents. NOTE! Trees have binary content, and as a result |
| 3980 | there is a special helper for showing that content, called |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 3981 | `git ls-tree`, which turns the binary content into a more easily |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3982 | readable form. |
| 3983 | |
| 3984 | It's especially instructive to look at "commit" objects, since those |
| 3985 | tend to be small and fairly self-explanatory. In particular, if you |
| 3986 | follow the convention of having the top commit name in `.git/HEAD`, |
| 3987 | you can do |
| 3988 | |
| 3989 | ------------------------------------------------- |
Junio C Hamano | fce7c7e | 2008-07-02 03:06:38 | [diff] [blame] | 3990 | $ git cat-file commit HEAD |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3991 | ------------------------------------------------- |
| 3992 | |
| 3993 | to see what the top commit was. |
| 3994 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 3995 | [[merging-multiple-trees]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 3996 | Merging multiple trees |
| 3997 | ---------------------- |
| 3998 | |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 3999 | Git can help you perform a three-way merge, which can in turn be |
| 4000 | used for a many-way merge by repeating the merge procedure several |
| 4001 | times. The usual situation is that you only do one three-way merge |
| 4002 | (reconciling two lines of history) and commit the result, but if |
| 4003 | you like to, you can merge several branches in one go. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4004 | |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 4005 | To perform a three-way merge, you start with the two commits you |
| 4006 | want to merge, find their closest common parent (a third commit), |
| 4007 | and compare the trees corresponding to these three commits. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4008 | |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 4009 | To get the "base" for the merge, look up the common parent of two |
| 4010 | commits: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4011 | |
| 4012 | ------------------------------------------------- |
Junio C Hamano | fce7c7e | 2008-07-02 03:06:38 | [diff] [blame] | 4013 | $ git merge-base <commit1> <commit2> |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4014 | ------------------------------------------------- |
| 4015 | |
Junio C Hamano | e6f28d0 | 2013-09-17 21:34:00 | [diff] [blame] | 4016 | This prints the name of a commit they are both based on. You should |
| 4017 | now look up the tree objects of those commits, which you can easily |
| 4018 | do with |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4019 | |
| 4020 | ------------------------------------------------- |
Junio C Hamano | fce7c7e | 2008-07-02 03:06:38 | [diff] [blame] | 4021 | $ git cat-file commit <commitname> | head -1 |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4022 | ------------------------------------------------- |
| 4023 | |
| 4024 | since the tree object information is always the first line in a commit |
| 4025 | object. |
| 4026 | |
| 4027 | Once you know the three trees you are going to merge (the one "original" |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 4028 | tree, aka the common tree, and the two "result" trees, aka the branches |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4029 | you want to merge), you do a "merge" read into the index. This will |
| 4030 | complain if it has to throw away your old index contents, so you should |
Junio C Hamano | 764a667 | 2007-10-23 01:23:31 | [diff] [blame] | 4031 | make sure that you've committed those--in fact you would normally |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4032 | always do a merge against your last commit (which should thus match what |
| 4033 | you have in your current index anyway). |
| 4034 | |
| 4035 | To do the merge, do |
| 4036 | |
| 4037 | ------------------------------------------------- |
Junio C Hamano | fce7c7e | 2008-07-02 03:06:38 | [diff] [blame] | 4038 | $ git read-tree -m -u <origtree> <yourtree> <targettree> |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4039 | ------------------------------------------------- |
| 4040 | |
| 4041 | which will do all trivial merge operations for you directly in the |
| 4042 | index file, and you can just write the result out with |
Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 4043 | `git write-tree`. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4044 | |
| 4045 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 4046 | [[merging-multiple-trees-2]] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4047 | Merging multiple trees, continued |
| 4048 | --------------------------------- |
| 4049 | |
| 4050 | Sadly, many merges aren't trivial. If there are files that have |
Junio C Hamano | 764a667 | 2007-10-23 01:23:31 | [diff] [blame] | 4051 | been added, moved or removed, or if both branches have modified the |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4052 | same file, you will be left with an index tree that contains "merge |
| 4053 | entries" in it. Such an index tree can 'NOT' be written out to a tree |
| 4054 | object, and you will have to resolve any such merge clashes using |
| 4055 | other tools before you can write out the result. |
| 4056 | |
Junio C Hamano | fce7c7e | 2008-07-02 03:06:38 | [diff] [blame] | 4057 | You can examine such index state with `git ls-files --unmerged` |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4058 | command. An example: |
| 4059 | |
| 4060 | ------------------------------------------------ |
Junio C Hamano | fce7c7e | 2008-07-02 03:06:38 | [diff] [blame] | 4061 | $ git read-tree -m $orig HEAD $target |
| 4062 | $ git ls-files --unmerged |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4063 | 100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello.c |
| 4064 | 100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello.c |
| 4065 | 100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello.c |
| 4066 | ------------------------------------------------ |
| 4067 | |
Junio C Hamano | fce7c7e | 2008-07-02 03:06:38 | [diff] [blame] | 4068 | Each line of the `git ls-files --unmerged` output begins with |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 4069 | the blob mode bits, blob SHA-1, 'stage number', and the |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 4070 | filename. The 'stage number' is Git's way to say which tree it |
Junio C Hamano | 44dcd49 | 2012-07-24 04:35:38 | [diff] [blame] | 4071 | came from: stage 1 corresponds to the `$orig` tree, stage 2 to |
| 4072 | the `HEAD` tree, and stage 3 to the `$target` tree. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4073 | |
| 4074 | Earlier we said that trivial merges are done inside |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 4075 | `git read-tree -m`. For example, if the file did not change |
Junio C Hamano | d75148a | 2014-04-08 19:48:38 | [diff] [blame] | 4076 | from `$orig` to `HEAD` or `$target`, or if the file changed |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4077 | from `$orig` to `HEAD` and `$orig` to `$target` the same way, |
| 4078 | obviously the final outcome is what is in `HEAD`. What the |
| 4079 | above example shows is that file `hello.c` was changed from |
| 4080 | `$orig` to `HEAD` and `$orig` to `$target` in a different way. |
| 4081 | You could resolve this by running your favorite 3-way merge |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 4082 | program, e.g. `diff3`, `merge`, or Git's own merge-file, on |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 4083 | the blob objects from these three stages yourself, like this: |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4084 | |
| 4085 | ------------------------------------------------ |
Junio C Hamano | fce7c7e | 2008-07-02 03:06:38 | [diff] [blame] | 4086 | $ git cat-file blob 263414f... >hello.c~1 |
| 4087 | $ git cat-file blob 06fa6a2... >hello.c~2 |
| 4088 | $ git cat-file blob cc44c73... >hello.c~3 |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 4089 | $ git merge-file hello.c~2 hello.c~1 hello.c~3 |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4090 | ------------------------------------------------ |
| 4091 | |
| 4092 | This would leave the merge result in `hello.c~2` file, along |
| 4093 | with conflict markers if there are conflicts. After verifying |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 4094 | the merge result makes sense, you can tell Git what the final |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4095 | merge result for this file is by: |
| 4096 | |
| 4097 | ------------------------------------------------- |
| 4098 | $ mv -f hello.c~2 hello.c |
Junio C Hamano | fce7c7e | 2008-07-02 03:06:38 | [diff] [blame] | 4099 | $ git update-index hello.c |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4100 | ------------------------------------------------- |
| 4101 | |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 4102 | When a path is in the "unmerged" state, running `git update-index` for |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 4103 | that path tells Git to mark the path resolved. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4104 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 4105 | The above is the description of a Git merge at the lowest level, |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4106 | to help you understand what conceptually happens under the hood. |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 4107 | In practice, nobody, not even Git itself, runs `git cat-file` three times |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 4108 | for this. There is a `git merge-index` program that extracts the |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4109 | stages to temporary files and calls a "merge" script on it: |
| 4110 | |
| 4111 | ------------------------------------------------- |
Junio C Hamano | fce7c7e | 2008-07-02 03:06:38 | [diff] [blame] | 4112 | $ git merge-index git-merge-one-file hello.c |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4113 | ------------------------------------------------- |
| 4114 | |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 4115 | and that is what higher level `git merge -s resolve` is implemented with. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4116 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 4117 | [[hacking-git]] |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 4118 | Hacking Git |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 4119 | =========== |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4120 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 4121 | This chapter covers internal details of the Git implementation which |
| 4122 | probably only Git developers need to understand. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4123 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 4124 | [[object-details]] |
| 4125 | Object storage format |
| 4126 | --------------------- |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4127 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 4128 | All objects have a statically determined "type" which identifies the |
| 4129 | format of the object (i.e. how it is used, and how it can refer to other |
| 4130 | objects). There are currently four different object types: "blob", |
| 4131 | "tree", "commit", and "tag". |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4132 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 4133 | Regardless of object type, all objects share the following |
| 4134 | characteristics: they are all deflated with zlib, and have a header |
| 4135 | that not only specifies their type, but also provides size information |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 4136 | about the data in the object. It's worth noting that the SHA-1 hash |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 4137 | that is used to name the object is the hash of the original data |
| 4138 | plus this header, so `sha1sum` 'file' does not match the object name |
| 4139 | for 'file'. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4140 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 4141 | As a result, the general consistency of an object can always be tested |
| 4142 | independently of the contents or the type of the object: all objects can |
| 4143 | be validated by verifying that (a) their hashes match the content of the |
| 4144 | file and (b) the object successfully inflates to a stream of bytes that |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 4145 | forms a sequence of |
| 4146 | `<ascii type without space> + <space> + <ascii decimal size> + |
| 4147 | <byte\0> + <binary object data>`. |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4148 | |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 4149 | The structured objects can further have their structure and |
| 4150 | connectivity to other objects verified. This is generally done with |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 4151 | the `git fsck` program, which generates a full dependency graph |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 4152 | of all objects, and verifies their internal consistency (in addition |
| 4153 | to just verifying their superficial consistency through the hash). |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4154 | |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4155 | [[birdview-on-the-source-code]] |
| 4156 | A birds-eye view of Git's source code |
| 4157 | ------------------------------------- |
| 4158 | |
| 4159 | It is not always easy for new developers to find their way through Git's |
| 4160 | source code. This section gives you a little guidance to show where to |
| 4161 | start. |
| 4162 | |
| 4163 | A good place to start is with the contents of the initial commit, with: |
| 4164 | |
| 4165 | ---------------------------------------------------- |
| 4166 | $ git checkout e83c5163 |
| 4167 | ---------------------------------------------------- |
| 4168 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 4169 | The initial revision lays the foundation for almost everything Git has |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4170 | today, but is small enough to read in one sitting. |
| 4171 | |
| 4172 | Note that terminology has changed since that revision. For example, the |
| 4173 | README in that revision uses the word "changeset" to describe what we |
| 4174 | now call a <<def_commit_object,commit>>. |
| 4175 | |
Junio C Hamano | d32738e | 2008-07-09 19:53:42 | [diff] [blame] | 4176 | Also, we do not call it "cache" any more, but rather "index"; however, the |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4177 | file is still called `cache.h`. Remark: Not much reason to change it now, |
| 4178 | especially since there is no good single name for it anyway, because it is |
| 4179 | basically _the_ header file which is included by _all_ of Git's C sources. |
| 4180 | |
| 4181 | If you grasp the ideas in that initial commit, you should check out a |
| 4182 | more recent version and skim `cache.h`, `object.h` and `commit.h`. |
| 4183 | |
| 4184 | In the early days, Git (in the tradition of UNIX) was a bunch of programs |
| 4185 | which were extremely simple, and which you used in scripts, piping the |
| 4186 | output of one into another. This turned out to be good for initial |
| 4187 | development, since it was easier to test new things. However, recently |
| 4188 | many of these parts have become builtins, and some of the core has been |
| 4189 | "libified", i.e. put into libgit.a for performance, portability reasons, |
| 4190 | and to avoid code duplication. |
| 4191 | |
| 4192 | By now, you know what the index is (and find the corresponding data |
| 4193 | structures in `cache.h`), and that there are just a couple of object types |
| 4194 | (blobs, trees, commits and tags) which inherit their common structure from |
| 4195 | `struct object`, which is their first member (and thus, you can cast e.g. |
| 4196 | `(struct object *)commit` to achieve the _same_ as `&commit->object`, i.e. |
| 4197 | get at the object name and flags). |
| 4198 | |
| 4199 | Now is a good point to take a break to let this information sink in. |
| 4200 | |
| 4201 | Next step: get familiar with the object naming. Read <<naming-commits>>. |
| 4202 | There are quite a few ways to name an object (and not only revisions!). |
| 4203 | All of these are handled in `sha1_name.c`. Just have a quick look at |
| 4204 | the function `get_sha1()`. A lot of the special handling is done by |
| 4205 | functions like `get_sha1_basic()` or the likes. |
| 4206 | |
| 4207 | This is just to get you into the groove for the most libified part of Git: |
| 4208 | the revision walker. |
| 4209 | |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 4210 | Basically, the initial version of `git log` was a shell script: |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4211 | |
| 4212 | ---------------------------------------------------------------- |
| 4213 | $ git-rev-list --pretty $(git-rev-parse --default HEAD "$@") | \ |
| 4214 | LESS=-S ${PAGER:-less} |
| 4215 | ---------------------------------------------------------------- |
| 4216 | |
| 4217 | What does this mean? |
| 4218 | |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 4219 | `git rev-list` is the original version of the revision walker, which |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4220 | _always_ printed a list of revisions to stdout. It is still functional, |
Junio C Hamano | 27a128b | 2009-08-13 01:23:00 | [diff] [blame] | 4221 | and needs to, since most new Git commands start out as scripts using |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 4222 | `git rev-list`. |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4223 | |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 4224 | `git rev-parse` is not as important any more; it was only used to filter out |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4225 | options that were relevant for the different plumbing commands that were |
| 4226 | called by the script. |
| 4227 | |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 4228 | Most of what `git rev-list` did is contained in `revision.c` and |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4229 | `revision.h`. It wraps the options in a struct named `rev_info`, which |
| 4230 | controls how and what revisions are walked, and more. |
| 4231 | |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 4232 | The original job of `git rev-parse` is now taken by the function |
Junio C Hamano | e1aeb5e | 2014-06-06 19:16:29 | [diff] [blame] | 4233 | `setup_revisions()`, which parses the revisions and the common command-line |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4234 | options for the revision walker. This information is stored in the struct |
Junio C Hamano | e1aeb5e | 2014-06-06 19:16:29 | [diff] [blame] | 4235 | `rev_info` for later consumption. You can do your own command-line option |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4236 | parsing after calling `setup_revisions()`. After that, you have to call |
| 4237 | `prepare_revision_walk()` for initialization, and then you can get the |
| 4238 | commits one by one with the function `get_revision()`. |
| 4239 | |
| 4240 | If you are interested in more details of the revision walking process, |
| 4241 | just have a look at the first implementation of `cmd_log()`; call |
Junio C Hamano | b76a686 | 2012-05-02 22:02:46 | [diff] [blame] | 4242 | `git show v1.3.0~155^2~4` and scroll down to that function (note that you |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4243 | no longer need to call `setup_pager()` directly). |
| 4244 | |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 4245 | Nowadays, `git log` is a builtin, which means that it is _contained_ in the |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4246 | command `git`. The source side of a builtin is |
| 4247 | |
Junio C Hamano | 3a3357e | 2013-06-26 23:20:56 | [diff] [blame] | 4248 | - a function called `cmd_<bla>`, typically defined in `builtin/<bla.c>` |
| 4249 | (note that older versions of Git used to have it in `builtin-<bla>.c` |
| 4250 | instead), and declared in `builtin.h`. |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4251 | |
| 4252 | - an entry in the `commands[]` array in `git.c`, and |
| 4253 | |
| 4254 | - an entry in `BUILTIN_OBJECTS` in the `Makefile`. |
| 4255 | |
| 4256 | Sometimes, more than one builtin is contained in one source file. For |
Junio C Hamano | 3a3357e | 2013-06-26 23:20:56 | [diff] [blame] | 4257 | example, `cmd_whatchanged()` and `cmd_log()` both reside in `builtin/log.c`, |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4258 | since they share quite a bit of code. In that case, the commands which are |
| 4259 | _not_ named like the `.c` file in which they live have to be listed in |
| 4260 | `BUILT_INS` in the `Makefile`. |
| 4261 | |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 4262 | `git log` looks more complicated in C than it does in the original script, |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4263 | but that allows for a much greater flexibility and performance. |
| 4264 | |
| 4265 | Here again it is a good point to take a pause. |
| 4266 | |
| 4267 | Lesson three is: study the code. Really, it is the best way to learn about |
| 4268 | the organization of Git (after you know the basic concepts). |
| 4269 | |
| 4270 | So, think about something which you are interested in, say, "how can I |
| 4271 | access a blob just knowing the object name of it?". The first step is to |
| 4272 | find a Git command with which you can do it. In this example, it is either |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 4273 | `git show` or `git cat-file`. |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4274 | |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 4275 | For the sake of clarity, let's stay with `git cat-file`, because it |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4276 | |
| 4277 | - is plumbing, and |
| 4278 | |
| 4279 | - was around even in the initial commit (it literally went only through |
Junio C Hamano | 3a3357e | 2013-06-26 23:20:56 | [diff] [blame] | 4280 | some 20 revisions as `cat-file.c`, was renamed to `builtin/cat-file.c` |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4281 | when made a builtin, and then saw less than 10 versions). |
| 4282 | |
Junio C Hamano | 3a3357e | 2013-06-26 23:20:56 | [diff] [blame] | 4283 | So, look into `builtin/cat-file.c`, search for `cmd_cat_file()` and look what |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4284 | it does. |
| 4285 | |
| 4286 | ------------------------------------------------------------------ |
| 4287 | git_config(git_default_config); |
| 4288 | if (argc != 3) |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 4289 | usage("git cat-file [-t|-s|-e|-p|<type>] <sha1>"); |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4290 | if (get_sha1(argv[2], sha1)) |
| 4291 | die("Not a valid object name %s", argv[2]); |
| 4292 | ------------------------------------------------------------------ |
| 4293 | |
| 4294 | Let's skip over the obvious details; the only really interesting part |
| 4295 | here is the call to `get_sha1()`. It tries to interpret `argv[2]` as an |
| 4296 | object name, and if it refers to an object which is present in the current |
| 4297 | repository, it writes the resulting SHA-1 into the variable `sha1`. |
| 4298 | |
| 4299 | Two things are interesting here: |
| 4300 | |
| 4301 | - `get_sha1()` returns 0 on _success_. This might surprise some new |
| 4302 | Git hackers, but there is a long tradition in UNIX to return different |
Junio C Hamano | 764a667 | 2007-10-23 01:23:31 | [diff] [blame] | 4303 | negative numbers in case of different errors--and 0 on success. |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4304 | |
| 4305 | - the variable `sha1` in the function signature of `get_sha1()` is `unsigned |
Junio C Hamano | b76a686 | 2012-05-02 22:02:46 | [diff] [blame] | 4306 | char *`, but is actually expected to be a pointer to `unsigned |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4307 | char[20]`. This variable will contain the 160-bit SHA-1 of the given |
Junio C Hamano | b76a686 | 2012-05-02 22:02:46 | [diff] [blame] | 4308 | commit. Note that whenever a SHA-1 is passed as `unsigned char *`, it |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4309 | is the binary representation, as opposed to the ASCII representation in |
| 4310 | hex characters, which is passed as `char *`. |
| 4311 | |
| 4312 | You will see both of these things throughout the code. |
| 4313 | |
| 4314 | Now, for the meat: |
| 4315 | |
| 4316 | ----------------------------------------------------------------------------- |
| 4317 | case 0: |
| 4318 | buf = read_object_with_reference(sha1, argv[1], &size, NULL); |
| 4319 | ----------------------------------------------------------------------------- |
| 4320 | |
| 4321 | This is how you read a blob (actually, not only a blob, but any type of |
| 4322 | object). To know how the function `read_object_with_reference()` actually |
| 4323 | works, find the source code for it (something like `git grep |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 4324 | read_object_with | grep ":[a-z]"` in the Git repository), and read |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4325 | the source. |
| 4326 | |
| 4327 | To find out how the result can be used, just read on in `cmd_cat_file()`: |
| 4328 | |
| 4329 | ----------------------------------- |
| 4330 | write_or_die(1, buf, size); |
| 4331 | ----------------------------------- |
| 4332 | |
| 4333 | Sometimes, you do not know where to look for a feature. In many such cases, |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 4334 | it helps to search through the output of `git log`, and then `git show` the |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4335 | corresponding commit. |
| 4336 | |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 4337 | Example: If you know that there was some test case for `git bundle`, but |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4338 | do not remember where it was (yes, you _could_ `git grep bundle t/`, but that |
| 4339 | does not illustrate the point!): |
| 4340 | |
| 4341 | ------------------------ |
| 4342 | $ git log --no-merges t/ |
| 4343 | ------------------------ |
| 4344 | |
| 4345 | In the pager (`less`), just search for "bundle", go a few lines back, |
| 4346 | and see that it is in commit 18449ab0... Now just copy this object name, |
| 4347 | and paste it into the command line |
| 4348 | |
| 4349 | ------------------- |
| 4350 | $ git show 18449ab0 |
| 4351 | ------------------- |
| 4352 | |
| 4353 | Voila. |
| 4354 | |
| 4355 | Another example: Find out what to do in order to make some script a |
| 4356 | builtin: |
| 4357 | |
| 4358 | ------------------------------------------------- |
Junio C Hamano | 3a3357e | 2013-06-26 23:20:56 | [diff] [blame] | 4359 | $ git log --no-merges --diff-filter=A builtin/*.c |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4360 | ------------------------------------------------- |
| 4361 | |
| 4362 | You see, Git is actually the best tool to find out about the source of Git |
| 4363 | itself! |
| 4364 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 4365 | [[glossary]] |
Junio C Hamano | bf984de | 2009-11-23 06:11:19 | [diff] [blame] | 4366 | Git Glossary |
Junio C Hamano | 9e1793f | 2008-06-02 07:31:16 | [diff] [blame] | 4367 | ============ |
| 4368 | |
| 4369 | include::glossary-content.txt[] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4370 | |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4371 | [[git-quick-start]] |
Junio C Hamano | f614c64 | 2007-06-11 01:21:54 | [diff] [blame] | 4372 | Appendix A: Git Quick Reference |
| 4373 | =============================== |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4374 | |
Junio C Hamano | f614c64 | 2007-06-11 01:21:54 | [diff] [blame] | 4375 | This is a quick summary of the major commands; the previous chapters |
| 4376 | explain how these work in more detail. |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4377 | |
| 4378 | [[quick-creating-a-new-repository]] |
| 4379 | Creating a new repository |
| 4380 | ------------------------- |
| 4381 | |
| 4382 | From a tarball: |
| 4383 | |
| 4384 | ----------------------------------------------- |
| 4385 | $ tar xzf project.tar.gz |
| 4386 | $ cd project |
| 4387 | $ git init |
| 4388 | Initialized empty Git repository in .git/ |
| 4389 | $ git add . |
| 4390 | $ git commit |
| 4391 | ----------------------------------------------- |
| 4392 | |
| 4393 | From a remote repository: |
| 4394 | |
| 4395 | ----------------------------------------------- |
| 4396 | $ git clone git://example.com/pub/project.git |
| 4397 | $ cd project |
| 4398 | ----------------------------------------------- |
| 4399 | |
| 4400 | [[managing-branches]] |
| 4401 | Managing branches |
| 4402 | ----------------- |
| 4403 | |
| 4404 | ----------------------------------------------- |
| 4405 | $ git branch # list all local branches in this repo |
| 4406 | $ git checkout test # switch working directory to branch "test" |
| 4407 | $ git branch new # create branch "new" starting at current HEAD |
| 4408 | $ git branch -d new # delete branch "new" |
| 4409 | ----------------------------------------------- |
| 4410 | |
Junio C Hamano | 764a667 | 2007-10-23 01:23:31 | [diff] [blame] | 4411 | Instead of basing a new branch on current HEAD (the default), use: |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4412 | |
| 4413 | ----------------------------------------------- |
| 4414 | $ git branch new test # branch named "test" |
| 4415 | $ git branch new v2.6.15 # tag named v2.6.15 |
| 4416 | $ git branch new HEAD^ # commit before the most recent |
| 4417 | $ git branch new HEAD^^ # commit before that |
| 4418 | $ git branch new test~10 # ten commits before tip of branch "test" |
| 4419 | ----------------------------------------------- |
| 4420 | |
| 4421 | Create and switch to a new branch at the same time: |
| 4422 | |
| 4423 | ----------------------------------------------- |
| 4424 | $ git checkout -b new v2.6.15 |
| 4425 | ----------------------------------------------- |
| 4426 | |
| 4427 | Update and examine branches from the repository you cloned from: |
| 4428 | |
| 4429 | ----------------------------------------------- |
| 4430 | $ git fetch # update |
| 4431 | $ git branch -r # list |
| 4432 | origin/master |
| 4433 | origin/next |
| 4434 | ... |
| 4435 | $ git checkout -b masterwork origin/master |
| 4436 | ----------------------------------------------- |
| 4437 | |
| 4438 | Fetch a branch from a different repository, and give it a new |
| 4439 | name in your repository: |
| 4440 | |
| 4441 | ----------------------------------------------- |
| 4442 | $ git fetch git://example.com/project.git theirbranch:mybranch |
| 4443 | $ git fetch git://example.com/project.git v2.6.15:mybranch |
| 4444 | ----------------------------------------------- |
| 4445 | |
| 4446 | Keep a list of repositories you work with regularly: |
| 4447 | |
| 4448 | ----------------------------------------------- |
| 4449 | $ git remote add example git://example.com/project.git |
| 4450 | $ git remote # list remote repositories |
| 4451 | example |
| 4452 | origin |
| 4453 | $ git remote show example # get details |
| 4454 | * remote example |
| 4455 | URL: git://example.com/project.git |
| 4456 | Tracked remote branches |
Junio C Hamano | edc174c | 2008-10-23 05:18:54 | [diff] [blame] | 4457 | master |
| 4458 | next |
| 4459 | ... |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4460 | $ git fetch example # update branches from example |
| 4461 | $ git branch -r # list all remote branches |
| 4462 | ----------------------------------------------- |
| 4463 | |
| 4464 | |
| 4465 | [[exploring-history]] |
| 4466 | Exploring history |
| 4467 | ----------------- |
| 4468 | |
| 4469 | ----------------------------------------------- |
| 4470 | $ gitk # visualize and browse history |
| 4471 | $ git log # list all commits |
| 4472 | $ git log src/ # ...modifying src/ |
| 4473 | $ git log v2.6.15..v2.6.16 # ...in v2.6.16, not in v2.6.15 |
| 4474 | $ git log master..test # ...in branch test, not in branch master |
| 4475 | $ git log test..master # ...in branch master, but not in test |
| 4476 | $ git log test...master # ...in one branch, not in both |
| 4477 | $ git log -S'foo()' # ...where difference contain "foo()" |
| 4478 | $ git log --since="2 weeks ago" |
| 4479 | $ git log -p # show patches as well |
| 4480 | $ git show # most recent commit |
| 4481 | $ git diff v2.6.15..v2.6.16 # diff between two tagged versions |
| 4482 | $ git diff v2.6.15..HEAD # diff with current head |
| 4483 | $ git grep "foo()" # search working directory for "foo()" |
| 4484 | $ git grep v2.6.15 "foo()" # search old tree for "foo()" |
| 4485 | $ git show v2.6.15:a.txt # look at old version of a.txt |
| 4486 | ----------------------------------------------- |
| 4487 | |
| 4488 | Search for regressions: |
| 4489 | |
| 4490 | ----------------------------------------------- |
| 4491 | $ git bisect start |
| 4492 | $ git bisect bad # current version is bad |
| 4493 | $ git bisect good v2.6.13-rc2 # last known good revision |
| 4494 | Bisecting: 675 revisions left to test after this |
| 4495 | # test here, then: |
| 4496 | $ git bisect good # if this revision is good, or |
| 4497 | $ git bisect bad # if this revision is bad. |
| 4498 | # repeat until done. |
| 4499 | ----------------------------------------------- |
| 4500 | |
| 4501 | [[making-changes]] |
| 4502 | Making changes |
| 4503 | -------------- |
| 4504 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 4505 | Make sure Git knows who to blame: |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4506 | |
| 4507 | ------------------------------------------------ |
| 4508 | $ cat >>~/.gitconfig <<\EOF |
| 4509 | [user] |
| 4510 | name = Your Name Comes Here |
| 4511 | email = you@yourdomain.example.com |
| 4512 | EOF |
| 4513 | ------------------------------------------------ |
| 4514 | |
| 4515 | Select file contents to include in the next commit, then make the |
| 4516 | commit: |
| 4517 | |
| 4518 | ----------------------------------------------- |
| 4519 | $ git add a.txt # updated file |
| 4520 | $ git add b.txt # new file |
| 4521 | $ git rm c.txt # old file |
| 4522 | $ git commit |
| 4523 | ----------------------------------------------- |
| 4524 | |
| 4525 | Or, prepare and create the commit in one step: |
| 4526 | |
| 4527 | ----------------------------------------------- |
| 4528 | $ git commit d.txt # use latest content only of d.txt |
| 4529 | $ git commit -a # use latest content of all tracked files |
| 4530 | ----------------------------------------------- |
| 4531 | |
| 4532 | [[merging]] |
| 4533 | Merging |
| 4534 | ------- |
| 4535 | |
| 4536 | ----------------------------------------------- |
| 4537 | $ git merge test # merge branch "test" into the current branch |
| 4538 | $ git pull git://example.com/project.git master |
| 4539 | # fetch and merge in remote branch |
| 4540 | $ git pull . test # equivalent to git merge test |
| 4541 | ----------------------------------------------- |
| 4542 | |
| 4543 | [[sharing-your-changes]] |
| 4544 | Sharing your changes |
| 4545 | -------------------- |
| 4546 | |
| 4547 | Importing or exporting patches: |
| 4548 | |
| 4549 | ----------------------------------------------- |
| 4550 | $ git format-patch origin..HEAD # format a patch for each commit |
| 4551 | # in HEAD but not in origin |
| 4552 | $ git am mbox # import patches from the mailbox "mbox" |
| 4553 | ----------------------------------------------- |
| 4554 | |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 4555 | Fetch a branch in a different Git repository, then merge into the |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4556 | current branch: |
| 4557 | |
| 4558 | ----------------------------------------------- |
| 4559 | $ git pull git://example.com/project.git theirbranch |
| 4560 | ----------------------------------------------- |
| 4561 | |
| 4562 | Store the fetched branch into a local branch before merging into the |
| 4563 | current branch: |
| 4564 | |
| 4565 | ----------------------------------------------- |
| 4566 | $ git pull git://example.com/project.git theirbranch:mybranch |
| 4567 | ----------------------------------------------- |
| 4568 | |
| 4569 | After creating commits on a local branch, update the remote |
| 4570 | branch with your commits: |
| 4571 | |
| 4572 | ----------------------------------------------- |
| 4573 | $ git push ssh://example.com/project.git mybranch:theirbranch |
| 4574 | ----------------------------------------------- |
| 4575 | |
| 4576 | When remote and local branch are both named "test": |
| 4577 | |
| 4578 | ----------------------------------------------- |
| 4579 | $ git push ssh://example.com/project.git test |
| 4580 | ----------------------------------------------- |
| 4581 | |
| 4582 | Shortcut version for a frequently used remote repository: |
| 4583 | |
| 4584 | ----------------------------------------------- |
| 4585 | $ git remote add example ssh://example.com/project.git |
| 4586 | $ git push example test |
| 4587 | ----------------------------------------------- |
| 4588 | |
| 4589 | [[repository-maintenance]] |
| 4590 | Repository maintenance |
| 4591 | ---------------------- |
| 4592 | |
| 4593 | Check for corruption: |
| 4594 | |
| 4595 | ----------------------------------------------- |
| 4596 | $ git fsck |
| 4597 | ----------------------------------------------- |
| 4598 | |
| 4599 | Recompress, remove unused cruft: |
| 4600 | |
| 4601 | ----------------------------------------------- |
| 4602 | $ git gc |
| 4603 | ----------------------------------------------- |
| 4604 | |
| 4605 | |
Junio C Hamano | 3d30fd5 | 2007-05-08 00:32:53 | [diff] [blame] | 4606 | [[todo]] |
Junio C Hamano | 75485c8 | 2007-05-19 04:20:33 | [diff] [blame] | 4607 | Appendix B: Notes and todo list for this manual |
| 4608 | =============================================== |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4609 | |
| 4610 | This is a work in progress. |
| 4611 | |
| 4612 | The basic requirements: |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 4613 | |
| 4614 | - It must be readable in order, from beginning to end, by someone |
| 4615 | intelligent with a basic grasp of the UNIX command line, but without |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 4616 | any special knowledge of Git. If necessary, any other prerequisites |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 4617 | should be specifically mentioned as they arise. |
| 4618 | - Whenever possible, section headings should clearly describe the task |
| 4619 | they explain how to do, in language that requires no more knowledge |
| 4620 | than necessary: for example, "importing patches into a project" rather |
Junio C Hamano | 5f9a6f0 | 2009-04-06 08:26:56 | [diff] [blame] | 4621 | than "the `git am` command" |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4622 | |
| 4623 | Think about how to create a clear chapter dependency graph that will |
| 4624 | allow people to get to important topics without necessarily reading |
| 4625 | everything in between. |
| 4626 | |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 4627 | Scan `Documentation/` for other stuff left out; in particular: |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 4628 | |
| 4629 | - howto's |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 4630 | - some of `technical/`? |
Junio C Hamano | 597ffcf | 2007-09-17 17:33:15 | [diff] [blame] | 4631 | - hooks |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 4632 | - list of commands in linkgit:git[1] |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4633 | |
| 4634 | Scan email archives for other stuff left out |
| 4635 | |
| 4636 | Scan man pages to see if any assume more background than this manual |
| 4637 | provides. |
| 4638 | |
| 4639 | Simplify beginning by suggesting disconnected head instead of |
| 4640 | temporary branch creation? |
| 4641 | |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4642 | Add more good examples. Entire sections of just cookbook examples |
| 4643 | might be a good idea; maybe make an "advanced examples" section a |
| 4644 | standard end-of-chapter section? |
| 4645 | |
| 4646 | Include cross-references to the glossary, where appropriate. |
| 4647 | |
| 4648 | Document shallow clones? See draft 1.5.0 release notes for some |
| 4649 | documentation. |
| 4650 | |
Junio C Hamano | ee1e428 | 2007-02-04 08:32:04 | [diff] [blame] | 4651 | Add a section on working with other version control systems, including |
Junio C Hamano | 8f62db9 | 2007-02-01 00:22:22 | [diff] [blame] | 4652 | CVS, Subversion, and just imports of series of release tarballs. |
| 4653 | |
| 4654 | More details on gitweb? |
| 4655 | |
| 4656 | Write a chapter on using plumbing and writing scripts. |
Junio C Hamano | f614c64 | 2007-06-11 01:21:54 | [diff] [blame] | 4657 | |
| 4658 | Alternates, clone -reference, etc. |
| 4659 | |
Junio C Hamano | ce3650e | 2007-11-26 04:20:11 | [diff] [blame] | 4660 | More on recovery from repository corruption. See: |
Junio C Hamano | 58f587a | 2013-07-22 19:20:59 | [diff] [blame] | 4661 | http://marc.info/?l=git&m=117263864820799&w=2 |
| 4662 | http://marc.info/?l=git&m=117147855503798&w=2 |