Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 1 | = Git User Manual |
J. Bruce Fields | 99eaefd | 2007-05-13 02:23:11 -0400 | [diff] [blame] | 2 | |
Firmin Martin | fc12b6f | 2021-04-04 06:07:39 +0200 | [diff] [blame] | 3 | [preface] |
| 4 | == Introduction |
| 5 | |
J. Bruce Fields | 99eaefd | 2007-05-13 02:23:11 -0400 | [diff] [blame] | 6 | Git is a fast distributed revision control system. |
| 7 | |
Brian Hetro | 0278307 | 2007-08-23 20:44:13 -0400 | [diff] [blame] | 8 | This manual is designed to be readable by someone with basic UNIX |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 9 | command-line skills, but no previous knowledge of Git. |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 10 | |
J. Bruce Fields | 2624d9a | 2007-05-12 22:55:40 -0400 | [diff] [blame] | 11 | <<repositories-and-branches>> and <<exploring-git-history>> explain how |
| 12 | to fetch and study a project using git--read these chapters to learn how |
| 13 | to build and test a particular version of a software project, search for |
| 14 | regressions, and so on. |
J. Bruce Fields | ef89f70 | 2007-01-20 21:41:48 -0500 | [diff] [blame] | 15 | |
J. Bruce Fields | 2624d9a | 2007-05-12 22:55:40 -0400 | [diff] [blame] | 16 | People needing to do actual development will also want to read |
Junio C Hamano | aa971cb | 2008-12-07 18:38:46 -0800 | [diff] [blame] | 17 | <<Developing-With-git>> and <<sharing-development>>. |
J. Bruce Fields | 6bd9b68 | 2007-01-07 22:58:14 -0500 | [diff] [blame] | 18 | |
| 19 | Further chapters cover more specialized topics. |
| 20 | |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 21 | Comprehensive reference documentation is available through the man |
Christian Couder | b3d9888 | 2008-11-17 16:42:47 +0100 | [diff] [blame] | 22 | pages, or linkgit:git-help[1] command. For example, for the command |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 23 | `git clone <repo>`, you can either use: |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 24 | |
| 25 | ------------------------------------------------ |
| 26 | $ man git-clone |
| 27 | ------------------------------------------------ |
| 28 | |
Christian Couder | b3d9888 | 2008-11-17 16:42:47 +0100 | [diff] [blame] | 29 | or: |
| 30 | |
| 31 | ------------------------------------------------ |
| 32 | $ git help clone |
| 33 | ------------------------------------------------ |
| 34 | |
| 35 | With the latter, you can use the manual viewer of your choice; see |
| 36 | linkgit:git-help[1] for more information. |
| 37 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 38 | See also <<git-quick-start>> for a brief overview of Git commands, |
J. Bruce Fields | 2624d9a | 2007-05-12 22:55:40 -0400 | [diff] [blame] | 39 | without any explanation. |
J. Bruce Fields | ef89f70 | 2007-01-20 21:41:48 -0500 | [diff] [blame] | 40 | |
J. Bruce Fields | 99f171b | 2007-06-05 18:33:27 -0400 | [diff] [blame] | 41 | Finally, see <<todo>> for ways that you can help make this manual more |
J. Bruce Fields | 2624d9a | 2007-05-12 22:55:40 -0400 | [diff] [blame] | 42 | complete. |
J. Bruce Fields | ef89f70 | 2007-01-20 21:41:48 -0500 | [diff] [blame] | 43 | |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 44 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 45 | [[repositories-and-branches]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 46 | == Repositories and Branches |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 47 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 48 | [[how-to-get-a-git-repository]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 49 | === How to get a Git repository |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 50 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 51 | It will be useful to have a Git repository to experiment with as you |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 52 | read this manual. |
| 53 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 54 | The best way to get one is by using the linkgit:git-clone[1] command to |
J. Bruce Fields | a5f90f3 | 2007-06-06 18:41:43 -0400 | [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: |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 57 | |
| 58 | ------------------------------------------------ |
W. Trevor King | 4b9ced2 | 2013-06-18 21:55:22 -0400 | [diff] [blame] | 59 | # Git itself (approx. 40MB download): |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 60 | $ git clone git://git.kernel.org/pub/scm/git/git.git |
W. Trevor King | 4b9ced2 | 2013-06-18 21:55:22 -0400 | [diff] [blame] | 61 | # the Linux kernel (approx. 640MB download): |
| 62 | $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [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 | |
W. Trevor King | 283efb0 | 2013-06-22 10:46:27 -0400 | [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 |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 70 | directory, you will see that it contains a copy of the project files, |
J. Bruce Fields | 0c4a33b | 2007-11-25 13:53:37 -0500 | [diff] [blame] | 71 | called the <<def_working_tree,working tree>>, together with a special |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 72 | top-level directory named `.git`, which contains all the information |
J. Bruce Fields | 0c4a33b | 2007-11-25 13:53:37 -0500 | [diff] [blame] | 73 | about the history of the project. |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 74 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 75 | [[how-to-check-out]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 76 | === How to check out a different version of a project |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 77 | |
J. Bruce Fields | a2ef9d6 | 2007-08-18 22:16:24 -0400 | [diff] [blame] | 78 | Git is best thought of as a tool for storing the history of a collection |
| 79 | of files. It stores the history as a compressed collection of |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 80 | interrelated snapshots of the project's contents. In Git each such |
J. Bruce Fields | a2ef9d6 | 2007-08-18 22:16:24 -0400 | [diff] [blame] | 81 | version is called a <<def_commit,commit>>. |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 82 | |
J. Bruce Fields | 0c4a33b | 2007-11-25 13:53:37 -0500 | [diff] [blame] | 83 | Those snapshots aren't necessarily all arranged in a single line from |
| 84 | oldest to newest; instead, work may simultaneously proceed along |
Gustaf Hendeby | 5728329 | 2007-12-31 14:31:35 +0100 | [diff] [blame] | 85 | parallel lines of development, called <<def_branch,branches>>, which may |
J. Bruce Fields | 0c4a33b | 2007-11-25 13:53:37 -0500 | [diff] [blame] | 86 | merge and diverge. |
| 87 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 88 | A single Git repository can track development on multiple branches. It |
J. Bruce Fields | 0c4a33b | 2007-11-25 13:53:37 -0500 | [diff] [blame] | 89 | does this by keeping a list of <<def_head,heads>> which reference the |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 90 | latest commit on each branch; the linkgit:git-branch[1] command shows |
J. Bruce Fields | 81b6c95 | 2007-03-18 23:02:14 -0400 | [diff] [blame] | 91 | you the list of branch heads: |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 92 | |
| 93 | ------------------------------------------------ |
| 94 | $ git branch |
| 95 | * master |
| 96 | ------------------------------------------------ |
| 97 | |
J. Bruce Fields | 4f75240 | 2007-04-16 00:37:13 -0400 | [diff] [blame] | 98 | A freshly cloned repository contains a single branch head, by default |
| 99 | named "master", with the working directory initialized to the state of |
| 100 | the project referred to by that branch head. |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 101 | |
J. Bruce Fields | 81b6c95 | 2007-03-18 23:02:14 -0400 | [diff] [blame] | 102 | Most projects also use <<def_tag,tags>>. Tags, like heads, are |
| 103 | references into the project's history, and can be listed using the |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 104 | linkgit:git-tag[1] command: |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 105 | |
| 106 | ------------------------------------------------ |
| 107 | $ git tag -l |
| 108 | v2.6.11 |
| 109 | v2.6.11-tree |
| 110 | v2.6.12 |
| 111 | v2.6.12-rc2 |
| 112 | v2.6.12-rc3 |
| 113 | v2.6.12-rc4 |
| 114 | v2.6.12-rc5 |
| 115 | v2.6.12-rc6 |
| 116 | v2.6.13 |
| 117 | ... |
| 118 | ------------------------------------------------ |
| 119 | |
J. Bruce Fields | fe4b3e5 | 2007-01-21 22:14:39 -0500 | [diff] [blame] | 120 | Tags are expected to always point at the same version of a project, |
J. Bruce Fields | 81b6c95 | 2007-03-18 23:02:14 -0400 | [diff] [blame] | 121 | while heads are expected to advance as development progresses. |
J. Bruce Fields | fe4b3e5 | 2007-01-21 22:14:39 -0500 | [diff] [blame] | 122 | |
J. Bruce Fields | 81b6c95 | 2007-03-18 23:02:14 -0400 | [diff] [blame] | 123 | Create a new branch head pointing to one of these versions and check it |
Nguyễn Thái Ngọc Duy | 328c6cb | 2019-03-29 17:39:19 +0700 | [diff] [blame] | 124 | out using linkgit:git-switch[1]: |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 125 | |
| 126 | ------------------------------------------------ |
Nguyễn Thái Ngọc Duy | 328c6cb | 2019-03-29 17:39:19 +0700 | [diff] [blame] | 127 | $ git switch -c new v2.6.13 |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 128 | ------------------------------------------------ |
| 129 | |
| 130 | The working directory then reflects the contents that the project had |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 131 | when it was tagged v2.6.13, and linkgit:git-branch[1] shows two |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 132 | branches, with an asterisk marking the currently checked-out branch: |
| 133 | |
| 134 | ------------------------------------------------ |
| 135 | $ git branch |
| 136 | master |
| 137 | * new |
| 138 | ------------------------------------------------ |
| 139 | |
| 140 | If you decide that you'd rather see version 2.6.17, you can modify |
| 141 | the current branch to point at v2.6.17 instead, with |
| 142 | |
| 143 | ------------------------------------------------ |
| 144 | $ git reset --hard v2.6.17 |
| 145 | ------------------------------------------------ |
| 146 | |
J. Bruce Fields | 81b6c95 | 2007-03-18 23:02:14 -0400 | [diff] [blame] | 147 | Note that if the current branch head was your only reference to a |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 148 | particular point in history, then resetting that branch may leave you |
J. Bruce Fields | 81b6c95 | 2007-03-18 23:02:14 -0400 | [diff] [blame] | 149 | with no way to find the history it used to point to; so use this command |
| 150 | carefully. |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 151 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 152 | [[understanding-commits]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 153 | === Understanding History: Commits |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 154 | |
| 155 | Every change in the history of a project is represented by a commit. |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 156 | The linkgit:git-show[1] command shows the most recent commit on the |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 157 | current branch: |
| 158 | |
| 159 | ------------------------------------------------ |
| 160 | $ git show |
J. Bruce Fields | e2618ff | 2007-08-19 11:14:21 -0400 | [diff] [blame] | 161 | commit 17cf781661e6d38f737f15f53ab552f1e95960d7 |
| 162 | Author: Linus Torvalds <torvalds@ppc970.osdl.org.(none)> |
| 163 | Date: Tue Apr 19 14:11:06 2005 -0700 |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 164 | |
J. Bruce Fields | e2618ff | 2007-08-19 11:14:21 -0400 | [diff] [blame] | 165 | Remove duplicate getenv(DB_ENVIRONMENT) call |
Junio C Hamano | a6080a0 | 2007-06-07 00:04:01 -0700 | [diff] [blame] | 166 | |
J. Bruce Fields | e2618ff | 2007-08-19 11:14:21 -0400 | [diff] [blame] | 167 | Noted by Tony Luck. |
Junio C Hamano | a6080a0 | 2007-06-07 00:04:01 -0700 | [diff] [blame] | 168 | |
J. Bruce Fields | e2618ff | 2007-08-19 11:14:21 -0400 | [diff] [blame] | 169 | diff --git a/init-db.c b/init-db.c |
| 170 | index 65898fa..b002dc6 100644 |
| 171 | --- a/init-db.c |
| 172 | +++ b/init-db.c |
| 173 | @@ -7,7 +7,7 @@ |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 174 | |
J. Bruce Fields | e2618ff | 2007-08-19 11:14:21 -0400 | [diff] [blame] | 175 | int main(int argc, char **argv) |
| 176 | { |
| 177 | - char *sha1_dir = getenv(DB_ENVIRONMENT), *path; |
| 178 | + char *sha1_dir, *path; |
| 179 | int len, i; |
| 180 | |
| 181 | if (mkdir(".git", 0755) < 0) { |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 182 | ------------------------------------------------ |
| 183 | |
| 184 | As you can see, a commit shows who made the latest change, what they |
| 185 | did, and why. |
| 186 | |
J. Bruce Fields | 3512193 | 2007-03-03 14:04:42 -0500 | [diff] [blame] | 187 | Every commit has a 40-hexdigit id, sometimes called the "object name" or the |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 188 | "SHA-1 id", shown on the first line of the `git show` output. You can usually |
J. Bruce Fields | 3512193 | 2007-03-03 14:04:42 -0500 | [diff] [blame] | 189 | refer to a commit by a shorter name, such as a tag or a branch name, but this |
| 190 | longer name can also be useful. Most importantly, it is a globally unique |
| 191 | name for this commit: so if you tell somebody else the object name (for |
| 192 | example in email), then you are guaranteed that name will refer to the same |
| 193 | commit in their repository that it does in yours (assuming their repository |
| 194 | has that commit at all). Since the object name is computed as a hash over the |
| 195 | contents of the commit, you are guaranteed that the commit can never change |
| 196 | without its name also changing. |
| 197 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 198 | In fact, in <<git-concepts>> we shall see that everything stored in Git |
J. Bruce Fields | 3512193 | 2007-03-03 14:04:42 -0500 | [diff] [blame] | 199 | history, including file data and directory contents, is stored in an object |
| 200 | with a name that is a hash of its contents. |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 201 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 202 | [[understanding-reachability]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 203 | ==== Understanding history: commits, parents, and reachability |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 204 | |
| 205 | Every commit (except the very first commit in a project) also has a |
| 206 | parent commit which shows what happened before this commit. |
| 207 | Following the chain of parents will eventually take you back to the |
| 208 | beginning of the project. |
| 209 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 210 | However, the commits do not form a simple list; Git allows lines of |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 211 | development to diverge and then reconverge, and the point where two |
| 212 | lines of development reconverge is called a "merge". The commit |
| 213 | representing a merge can therefore have more than one parent, with |
| 214 | each parent representing the most recent commit on one of the lines |
| 215 | of development leading to that point. |
| 216 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 217 | The best way to see how this works is using the linkgit:gitk[1] |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 218 | command; running gitk now on a Git repository and looking for merge |
Thomas Ackermann | ddd4dde | 2013-08-27 19:59:21 +0200 | [diff] [blame] | 219 | commits will help understand how Git organizes history. |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 220 | |
| 221 | In the following, we say that commit X is "reachable" from commit Y |
| 222 | if commit X is an ancestor of commit Y. Equivalently, you could say |
Brian Hetro | 0278307 | 2007-08-23 20:44:13 -0400 | [diff] [blame] | 223 | that Y is a descendant of X, or that there is a chain of parents |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 224 | leading from commit Y to commit X. |
| 225 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 226 | [[history-diagrams]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 227 | ==== Understanding history: History diagrams |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 228 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 229 | We will sometimes represent Git history using diagrams like the one |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 230 | below. Commits are shown as "o", and the links between them with |
| 231 | lines drawn with - / and \. Time goes left to right: |
| 232 | |
J. Bruce Fields | 1dc71a9 | 2007-03-10 22:38:13 -0500 | [diff] [blame] | 233 | |
| 234 | ................................................ |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 235 | o--o--o <-- Branch A |
| 236 | / |
| 237 | o--o--o <-- master |
| 238 | \ |
| 239 | o--o--o <-- Branch B |
J. Bruce Fields | 1dc71a9 | 2007-03-10 22:38:13 -0500 | [diff] [blame] | 240 | ................................................ |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 241 | |
| 242 | If we need to talk about a particular commit, the character "o" may |
| 243 | be replaced with another letter or number. |
| 244 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 245 | [[what-is-a-branch]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 246 | ==== Understanding history: What is a branch? |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 247 | |
J. Bruce Fields | 81b6c95 | 2007-03-18 23:02:14 -0400 | [diff] [blame] | 248 | When we need to be precise, we will use the word "branch" to mean a line |
| 249 | of development, and "branch head" (or just "head") to mean a reference |
| 250 | to the most recent commit on a branch. In the example above, the branch |
| 251 | head named "A" is a pointer to one particular commit, but we refer to |
| 252 | the line of three commits leading up to that point as all being part of |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 253 | "branch A". |
| 254 | |
J. Bruce Fields | 81b6c95 | 2007-03-18 23:02:14 -0400 | [diff] [blame] | 255 | However, when no confusion will result, we often just use the term |
| 256 | "branch" both for branches and for branch heads. |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 257 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 258 | [[manipulating-branches]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 259 | === Manipulating branches |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 260 | |
| 261 | Creating, deleting, and modifying branches is quick and easy; here's |
| 262 | a summary of the commands: |
| 263 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 264 | `git branch`:: |
Thomas Ackermann | df47da7 | 2013-08-27 20:02:08 +0200 | [diff] [blame] | 265 | list all branches. |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 266 | `git branch <branch>`:: |
| 267 | create a new branch named `<branch>`, referencing the same |
Thomas Ackermann | df47da7 | 2013-08-27 20:02:08 +0200 | [diff] [blame] | 268 | point in history as the current branch. |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 269 | `git branch <branch> <start-point>`:: |
| 270 | create a new branch named `<branch>`, referencing |
| 271 | `<start-point>`, which may be specified any way you like, |
Thomas Ackermann | df47da7 | 2013-08-27 20:02:08 +0200 | [diff] [blame] | 272 | including using a branch name or a tag name. |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 273 | `git branch -d <branch>`:: |
Thomas Ackermann | df47da7 | 2013-08-27 20:02:08 +0200 | [diff] [blame] | 274 | delete the branch `<branch>`; if the branch is not fully |
| 275 | merged in its upstream branch or contained in the current branch, |
| 276 | this command will fail with a warning. |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 277 | `git branch -D <branch>`:: |
Thomas Ackermann | df47da7 | 2013-08-27 20:02:08 +0200 | [diff] [blame] | 278 | delete the branch `<branch>` irrespective of its merged status. |
Nguyễn Thái Ngọc Duy | 328c6cb | 2019-03-29 17:39:19 +0700 | [diff] [blame] | 279 | `git switch <branch>`:: |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 280 | make the current branch `<branch>`, updating the working |
Thomas Ackermann | df47da7 | 2013-08-27 20:02:08 +0200 | [diff] [blame] | 281 | directory to reflect the version referenced by `<branch>`. |
Nguyễn Thái Ngọc Duy | 328c6cb | 2019-03-29 17:39:19 +0700 | [diff] [blame] | 282 | `git switch -c <new> <start-point>`:: |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 283 | create a new branch `<new>` referencing `<start-point>`, and |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 284 | check it out. |
| 285 | |
J. Bruce Fields | 72a76c9 | 2007-04-16 00:37:14 -0400 | [diff] [blame] | 286 | The special symbol "HEAD" can always be used to refer to the current |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 287 | branch. In fact, Git uses a file named `HEAD` in the `.git` directory |
| 288 | to remember which branch is current: |
J. Bruce Fields | 72a76c9 | 2007-04-16 00:37:14 -0400 | [diff] [blame] | 289 | |
| 290 | ------------------------------------------------ |
| 291 | $ cat .git/HEAD |
| 292 | ref: refs/heads/master |
| 293 | ------------------------------------------------ |
| 294 | |
J. Bruce Fields | 25d9f3f | 2007-04-16 00:37:16 -0400 | [diff] [blame] | 295 | [[detached-head]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 296 | === Examining an old version without creating a new branch |
J. Bruce Fields | 72a76c9 | 2007-04-16 00:37:14 -0400 | [diff] [blame] | 297 | |
Nguyễn Thái Ngọc Duy | 328c6cb | 2019-03-29 17:39:19 +0700 | [diff] [blame] | 298 | The `git switch` command normally expects a branch head, but will also |
| 299 | accept an arbitrary commit when invoked with --detach; for example, |
| 300 | you can check out the commit referenced by a tag: |
J. Bruce Fields | 72a76c9 | 2007-04-16 00:37:14 -0400 | [diff] [blame] | 301 | |
| 302 | ------------------------------------------------ |
Nguyễn Thái Ngọc Duy | 328c6cb | 2019-03-29 17:39:19 +0700 | [diff] [blame] | 303 | $ git switch --detach v2.6.17 |
Thomas Ackermann | 95f9be5 | 2013-08-27 19:56:04 +0200 | [diff] [blame] | 304 | Note: checking out 'v2.6.17'. |
| 305 | |
| 306 | You are in 'detached HEAD' state. You can look around, make experimental |
| 307 | changes and commit them, and you can discard any commits you make in this |
Nguyễn Thái Ngọc Duy | 328c6cb | 2019-03-29 17:39:19 +0700 | [diff] [blame] | 308 | state without impacting any branches by performing another switch. |
Thomas Ackermann | 95f9be5 | 2013-08-27 19:56:04 +0200 | [diff] [blame] | 309 | |
| 310 | If you want to create a new branch to retain commits you create, you may |
Nguyễn Thái Ngọc Duy | 328c6cb | 2019-03-29 17:39:19 +0700 | [diff] [blame] | 311 | do so (now or later) by using -c with the switch command again. Example: |
Thomas Ackermann | 95f9be5 | 2013-08-27 19:56:04 +0200 | [diff] [blame] | 312 | |
Nguyễn Thái Ngọc Duy | 328c6cb | 2019-03-29 17:39:19 +0700 | [diff] [blame] | 313 | git switch -c new_branch_name |
Thomas Ackermann | 95f9be5 | 2013-08-27 19:56:04 +0200 | [diff] [blame] | 314 | |
Ann T Ropea | ca69d4d | 2017-12-06 01:20:42 +0100 | [diff] [blame] | 315 | HEAD is now at 427abfa Linux v2.6.17 |
J. Bruce Fields | 72a76c9 | 2007-04-16 00:37:14 -0400 | [diff] [blame] | 316 | ------------------------------------------------ |
| 317 | |
Felipe Contreras | a6e5ef7 | 2009-04-04 12:38:27 +0300 | [diff] [blame] | 318 | The HEAD then refers to the SHA-1 of the commit instead of to a branch, |
J. Bruce Fields | 72a76c9 | 2007-04-16 00:37:14 -0400 | [diff] [blame] | 319 | and git branch shows that you are no longer on a branch: |
| 320 | |
| 321 | ------------------------------------------------ |
| 322 | $ cat .git/HEAD |
| 323 | 427abfa28afedffadfca9dd8b067eb6d36bac53f |
J. Bruce Fields | 953f3d6 | 2007-04-18 00:20:46 -0400 | [diff] [blame] | 324 | $ git branch |
Thomas Ackermann | 95f9be5 | 2013-08-27 19:56:04 +0200 | [diff] [blame] | 325 | * (detached from v2.6.17) |
J. Bruce Fields | 72a76c9 | 2007-04-16 00:37:14 -0400 | [diff] [blame] | 326 | master |
| 327 | ------------------------------------------------ |
| 328 | |
| 329 | In this case we say that the HEAD is "detached". |
| 330 | |
J. Bruce Fields | 953f3d6 | 2007-04-18 00:20:46 -0400 | [diff] [blame] | 331 | This is an easy way to check out a particular version without having to |
| 332 | make up a name for the new branch. You can still create a new branch |
| 333 | (or tag) for this version later if you decide to. |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 334 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 335 | [[examining-remote-branches]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 336 | === Examining branches from a remote repository |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 337 | |
| 338 | The "master" branch that was created at the time you cloned is a copy |
| 339 | of the HEAD in the repository that you cloned from. That repository |
| 340 | may also have had other branches, though, and your local repository |
Matthieu Moy | 66a062a | 2010-11-02 22:06:20 +0100 | [diff] [blame] | 341 | keeps branches which track each of those remote branches, called |
| 342 | remote-tracking branches, which you |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 343 | can view using the `-r` option to linkgit:git-branch[1]: |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 344 | |
| 345 | ------------------------------------------------ |
| 346 | $ git branch -r |
| 347 | origin/HEAD |
| 348 | origin/html |
| 349 | origin/maint |
| 350 | origin/man |
| 351 | origin/master |
| 352 | origin/next |
Johannes Schindelin | 828197d | 2020-06-25 12:18:57 +0000 | [diff] [blame] | 353 | origin/seen |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 354 | origin/todo |
| 355 | ------------------------------------------------ |
| 356 | |
Matthieu Moy | 66a062a | 2010-11-02 22:06:20 +0100 | [diff] [blame] | 357 | In this example, "origin" is called a remote repository, or "remote" |
| 358 | for short. The branches of this repository are called "remote |
| 359 | branches" from our point of view. The remote-tracking branches listed |
| 360 | above were created based on the remote branches at clone time and will |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 361 | be updated by `git fetch` (hence `git pull`) and `git push`. See |
Matthieu Moy | 66a062a | 2010-11-02 22:06:20 +0100 | [diff] [blame] | 362 | <<Updating-a-repository-With-git-fetch>> for details. |
| 363 | |
Jonathan Nieder | 45dfd40 | 2010-11-02 16:31:27 +0100 | [diff] [blame] | 364 | You might want to build on one of these remote-tracking branches |
| 365 | on a branch of your own, just as you would for a tag: |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 366 | |
| 367 | ------------------------------------------------ |
Nguyễn Thái Ngọc Duy | 328c6cb | 2019-03-29 17:39:19 +0700 | [diff] [blame] | 368 | $ git switch -c my-todo-copy origin/todo |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 369 | ------------------------------------------------ |
| 370 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 371 | You can also check out `origin/todo` directly to examine it or |
Jonathan Nieder | 45dfd40 | 2010-11-02 16:31:27 +0100 | [diff] [blame] | 372 | write a one-off patch. See <<detached-head,detached head>>. |
| 373 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 374 | Note that the name "origin" is just the name that Git uses by default |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 375 | to refer to the repository that you cloned from. |
| 376 | |
| 377 | [[how-git-stores-references]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 378 | === Naming branches, tags, and other references |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 379 | |
| 380 | Branches, remote-tracking branches, and tags are all references to |
J. Bruce Fields | f60b964 | 2007-01-21 22:31:07 -0500 | [diff] [blame] | 381 | commits. All references are named with a slash-separated path name |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 382 | starting with `refs`; the names we've been using so far are actually |
J. Bruce Fields | f60b964 | 2007-01-21 22:31:07 -0500 | [diff] [blame] | 383 | shorthand: |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 384 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 385 | - The branch `test` is short for `refs/heads/test`. |
| 386 | - The tag `v2.6.18` is short for `refs/tags/v2.6.18`. |
| 387 | - `origin/master` is short for `refs/remotes/origin/master`. |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 388 | |
J. Bruce Fields | f60b964 | 2007-01-21 22:31:07 -0500 | [diff] [blame] | 389 | The full name is occasionally useful if, for example, there ever |
| 390 | exists a tag and a branch with the same name. |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 391 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 392 | (Newly created refs are actually stored in the `.git/refs` directory, |
J. Bruce Fields | fc74ecc | 2007-09-09 22:07:02 -0400 | [diff] [blame] | 393 | under the path given by their name. However, for efficiency reasons |
| 394 | they may also be packed together in a single file; see |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 395 | linkgit:git-pack-refs[1]). |
J. Bruce Fields | fc74ecc | 2007-09-09 22:07:02 -0400 | [diff] [blame] | 396 | |
J. Bruce Fields | c64415e | 2007-05-07 00:56:45 -0400 | [diff] [blame] | 397 | As another useful shortcut, the "HEAD" of a repository can be referred |
| 398 | to just using the name of that repository. So, for example, "origin" |
| 399 | is usually a shortcut for the HEAD branch in the repository "origin". |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 400 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 401 | For the complete list of paths which Git checks for references, and |
J. Bruce Fields | f60b964 | 2007-01-21 22:31:07 -0500 | [diff] [blame] | 402 | the order it uses to decide which to choose when there are multiple |
| 403 | references with the same shorthand name, see the "SPECIFYING |
Jonathan Nieder | 9d83e38 | 2010-10-11 11:03:32 -0500 | [diff] [blame] | 404 | REVISIONS" section of linkgit:gitrevisions[7]. |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 405 | |
Junio C Hamano | aa971cb | 2008-12-07 18:38:46 -0800 | [diff] [blame] | 406 | [[Updating-a-repository-With-git-fetch]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 407 | === Updating a repository with git fetch |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 408 | |
Jeremiah Mahler | 3c735e0 | 2014-05-27 19:23:32 -0700 | [diff] [blame] | 409 | After you clone a repository and commit a few changes of your own, you |
| 410 | may wish to check the original repository for updates. |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 411 | |
Jeremiah Mahler | 3c735e0 | 2014-05-27 19:23:32 -0700 | [diff] [blame] | 412 | The `git-fetch` command, with no arguments, will update all of the |
| 413 | remote-tracking branches to the latest version found in the original |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 414 | repository. It will not touch any of your own branches--not even the |
| 415 | "master" branch that was created for you on clone. |
| 416 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 417 | [[fetching-branches]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 418 | === Fetching branches from other repositories |
J. Bruce Fields | d5cd5de | 2007-01-09 00:18:09 -0500 | [diff] [blame] | 419 | |
| 420 | You can also track branches from repositories other than the one you |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 421 | cloned from, using linkgit:git-remote[1]: |
J. Bruce Fields | d5cd5de | 2007-01-09 00:18:09 -0500 | [diff] [blame] | 422 | |
| 423 | ------------------------------------------------- |
W. Trevor King | 34a25d4 | 2013-06-22 10:46:26 -0400 | [diff] [blame] | 424 | $ git remote add staging git://git.kernel.org/.../gregkh/staging.git |
| 425 | $ git fetch staging |
| 426 | ... |
| 427 | From git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging |
| 428 | * [new branch] master -> staging/master |
| 429 | * [new branch] staging-linus -> staging/staging-linus |
| 430 | * [new branch] staging-next -> staging/staging-next |
J. Bruce Fields | d5cd5de | 2007-01-09 00:18:09 -0500 | [diff] [blame] | 431 | ------------------------------------------------- |
| 432 | |
| 433 | New remote-tracking branches will be stored under the shorthand name |
W. Trevor King | 34a25d4 | 2013-06-22 10:46:26 -0400 | [diff] [blame] | 434 | that you gave `git remote add`, in this case `staging`: |
J. Bruce Fields | d5cd5de | 2007-01-09 00:18:09 -0500 | [diff] [blame] | 435 | |
| 436 | ------------------------------------------------- |
| 437 | $ git branch -r |
W. Trevor King | 34a25d4 | 2013-06-22 10:46:26 -0400 | [diff] [blame] | 438 | origin/HEAD -> origin/master |
| 439 | origin/master |
| 440 | staging/master |
| 441 | staging/staging-linus |
| 442 | staging/staging-next |
J. Bruce Fields | d5cd5de | 2007-01-09 00:18:09 -0500 | [diff] [blame] | 443 | ------------------------------------------------- |
| 444 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 445 | If you run `git fetch <remote>` later, the remote-tracking branches |
| 446 | for the named `<remote>` will be updated. |
J. Bruce Fields | d5cd5de | 2007-01-09 00:18:09 -0500 | [diff] [blame] | 447 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 448 | If you examine the file `.git/config`, you will see that Git has added |
J. Bruce Fields | d5cd5de | 2007-01-09 00:18:09 -0500 | [diff] [blame] | 449 | a new stanza: |
| 450 | |
| 451 | ------------------------------------------------- |
| 452 | $ cat .git/config |
| 453 | ... |
W. Trevor King | 34a25d4 | 2013-06-22 10:46:26 -0400 | [diff] [blame] | 454 | [remote "staging"] |
| 455 | url = git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging.git |
| 456 | fetch = +refs/heads/*:refs/remotes/staging/* |
J. Bruce Fields | d5cd5de | 2007-01-09 00:18:09 -0500 | [diff] [blame] | 457 | ... |
| 458 | ------------------------------------------------- |
| 459 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 460 | This is what causes Git to track the remote's branches; you may modify |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 461 | or delete these configuration options by editing `.git/config` with a |
J. Bruce Fields | fc90c53 | 2007-01-29 00:17:51 -0500 | [diff] [blame] | 462 | text editor. (See the "CONFIGURATION FILE" section of |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 463 | linkgit:git-config[1] for details.) |
J. Bruce Fields | d5cd5de | 2007-01-09 00:18:09 -0500 | [diff] [blame] | 464 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 465 | [[exploring-git-history]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 466 | == Exploring Git history |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 467 | |
| 468 | Git is best thought of as a tool for storing the history of a |
| 469 | collection of files. It does this by storing compressed snapshots of |
Junio C Hamano | 1130845 | 2007-07-24 01:58:51 -0700 | [diff] [blame] | 470 | the contents of a file hierarchy, together with "commits" which show |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 471 | the relationships between these snapshots. |
| 472 | |
| 473 | Git provides extremely flexible and fast tools for exploring the |
| 474 | history of a project. |
| 475 | |
Mike Coleman | aacd404 | 2007-02-02 00:25:30 -0600 | [diff] [blame] | 476 | We start with one specialized tool that is useful for finding the |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 477 | commit that introduced a bug into a project. |
| 478 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 479 | [[using-bisect]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 480 | === How to use bisect to find a regression |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 481 | |
| 482 | Suppose version 2.6.18 of your project worked, but the version at |
| 483 | "master" crashes. Sometimes the best way to find the cause of such a |
| 484 | regression is to perform a brute-force search through the project's |
| 485 | history to find the particular commit that caused the problem. The |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 486 | linkgit:git-bisect[1] command can help you do this: |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 487 | |
| 488 | ------------------------------------------------- |
| 489 | $ git bisect start |
| 490 | $ git bisect good v2.6.18 |
| 491 | $ git bisect bad master |
| 492 | Bisecting: 3537 revisions left to test after this |
| 493 | [65934a9a028b88e83e2b0f8b36618fe503349f8e] BLOCK: Make USB storage depend on SCSI rather than selecting it [try #6] |
| 494 | ------------------------------------------------- |
| 495 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 496 | If you run `git branch` at this point, you'll see that Git has |
Christian Couder | 0e25790 | 2008-07-31 05:22:40 +0200 | [diff] [blame] | 497 | temporarily moved you in "(no branch)". HEAD is now detached from any |
Ann T Ropea | f61d89e | 2017-12-03 22:27:38 +0100 | [diff] [blame] | 498 | branch and points directly to a commit (with commit id 65934) that |
Christian Couder | 0e25790 | 2008-07-31 05:22:40 +0200 | [diff] [blame] | 499 | is reachable from "master" but not from v2.6.18. Compile and test it, |
| 500 | and see whether it crashes. Assume it does crash. Then: |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 501 | |
| 502 | ------------------------------------------------- |
| 503 | $ git bisect bad |
| 504 | Bisecting: 1769 revisions left to test after this |
| 505 | [7eff82c8b1511017ae605f0c99ac275a7e21b867] i2c-core: Drop useless bitmaskings |
| 506 | ------------------------------------------------- |
| 507 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 508 | checks out an older version. Continue like this, telling Git at each |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 509 | stage whether the version it gives you is good or bad, and notice |
| 510 | that the number of revisions left to test is cut approximately in |
| 511 | half each time. |
| 512 | |
| 513 | After about 13 tests (in this case), it will output the commit id of |
| 514 | the guilty commit. You can then examine the commit with |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 515 | linkgit:git-show[1], find out who wrote it, and mail them your bug |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 516 | report with the commit id. Finally, run |
| 517 | |
| 518 | ------------------------------------------------- |
| 519 | $ git bisect reset |
| 520 | ------------------------------------------------- |
| 521 | |
Christian Couder | 0e25790 | 2008-07-31 05:22:40 +0200 | [diff] [blame] | 522 | to return you to the branch you were on before. |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 523 | |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 524 | Note that the version which `git bisect` checks out for you at each |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 525 | point is just a suggestion, and you're free to try a different |
| 526 | version if you think it would be a good idea. For example, |
| 527 | occasionally you may land on a commit that broke something unrelated; |
| 528 | run |
| 529 | |
| 530 | ------------------------------------------------- |
Jakub Narebski | 0448352 | 2007-04-03 18:27:28 +0200 | [diff] [blame] | 531 | $ git bisect visualize |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 532 | ------------------------------------------------- |
| 533 | |
| 534 | which will run gitk and label the commit it chose with a marker that |
Eric Hanchrow | 843c81d | 2008-07-08 13:00:30 -0700 | [diff] [blame] | 535 | says "bisect". Choose a safe-looking commit nearby, note its commit |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 536 | id, and check it out with: |
| 537 | |
| 538 | ------------------------------------------------- |
Ann T Ropea | f61d89e | 2017-12-03 22:27:38 +0100 | [diff] [blame] | 539 | $ git reset --hard fb47ddb2db |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 540 | ------------------------------------------------- |
| 541 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 542 | then test, run `bisect good` or `bisect bad` as appropriate, and |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 543 | continue. |
| 544 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 545 | Instead of `git bisect visualize` and then `git reset --hard |
Ann T Ropea | f61d89e | 2017-12-03 22:27:38 +0100 | [diff] [blame] | 546 | fb47ddb2db`, you might just want to tell Git that you want to skip |
Christian Couder | 0e25790 | 2008-07-31 05:22:40 +0200 | [diff] [blame] | 547 | the current commit: |
| 548 | |
| 549 | ------------------------------------------------- |
| 550 | $ git bisect skip |
| 551 | ------------------------------------------------- |
| 552 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 553 | In this case, though, Git may not eventually be able to tell the first |
Ralf Wildenhues | a0178ae | 2008-11-27 08:32:01 +0100 | [diff] [blame] | 554 | bad one between some first skipped commits and a later bad commit. |
Christian Couder | 0e25790 | 2008-07-31 05:22:40 +0200 | [diff] [blame] | 555 | |
| 556 | There are also ways to automate the bisecting process if you have a |
| 557 | test script that can tell a good from a bad commit. See |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 558 | linkgit:git-bisect[1] for more information about this and other `git |
| 559 | bisect` features. |
Christian Couder | 0e25790 | 2008-07-31 05:22:40 +0200 | [diff] [blame] | 560 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 561 | [[naming-commits]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 562 | === Naming commits |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 563 | |
| 564 | We have seen several ways of naming commits already: |
| 565 | |
J. Bruce Fields | d55ae92 | 2007-01-29 02:16:45 -0500 | [diff] [blame] | 566 | - 40-hexdigit object name |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 567 | - branch name: refers to the commit at the head of the given |
| 568 | branch |
| 569 | - tag name: refers to the commit pointed to by the given tag |
| 570 | (we've seen branches and tags are special cases of |
| 571 | <<how-git-stores-references,references>>). |
| 572 | - HEAD: refers to the head of the current branch |
| 573 | |
Junio C Hamano | eb6ae7f | 2007-01-10 18:11:53 -0800 | [diff] [blame] | 574 | There are many more; see the "SPECIFYING REVISIONS" section of the |
Jonathan Nieder | 9d83e38 | 2010-10-11 11:03:32 -0500 | [diff] [blame] | 575 | linkgit:gitrevisions[7] man page for the complete list of ways to |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 576 | name revisions. Some examples: |
| 577 | |
| 578 | ------------------------------------------------- |
J. Bruce Fields | d55ae92 | 2007-01-29 02:16:45 -0500 | [diff] [blame] | 579 | $ git show fb47ddb2 # the first few characters of the object name |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 580 | # are usually enough to specify it uniquely |
| 581 | $ git show HEAD^ # the parent of the HEAD commit |
| 582 | $ git show HEAD^^ # the grandparent |
| 583 | $ git show HEAD~4 # the great-great-grandparent |
| 584 | ------------------------------------------------- |
| 585 | |
| 586 | Recall that merge commits may have more than one parent; by default, |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 587 | `^` and `~` follow the first parent listed in the commit, but you can |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 588 | also choose: |
| 589 | |
| 590 | ------------------------------------------------- |
| 591 | $ git show HEAD^1 # show the first parent of HEAD |
| 592 | $ git show HEAD^2 # show the second parent of HEAD |
| 593 | ------------------------------------------------- |
| 594 | |
| 595 | In addition to HEAD, there are several other special names for |
| 596 | commits: |
| 597 | |
| 598 | Merges (to be discussed later), as well as operations such as |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 599 | `git reset`, which change the currently checked-out commit, generally |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 600 | set ORIG_HEAD to the value HEAD had before the current operation. |
| 601 | |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 602 | The `git fetch` operation always stores the head of the last fetched |
| 603 | branch in FETCH_HEAD. For example, if you run `git fetch` without |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 604 | specifying a local branch as the target of the operation |
| 605 | |
| 606 | ------------------------------------------------- |
| 607 | $ git fetch git://example.com/proj.git theirbranch |
| 608 | ------------------------------------------------- |
| 609 | |
| 610 | the fetched commits will still be available from FETCH_HEAD. |
| 611 | |
| 612 | When we discuss merges we'll also see the special name MERGE_HEAD, |
| 613 | which refers to the other branch that we're merging in to the current |
| 614 | branch. |
| 615 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 616 | The linkgit:git-rev-parse[1] command is a low-level command that is |
J. Bruce Fields | d55ae92 | 2007-01-29 02:16:45 -0500 | [diff] [blame] | 617 | occasionally useful for translating some name for a commit to the object |
| 618 | name for that commit: |
J. Bruce Fields | aec053b | 2007-01-10 23:17:00 -0500 | [diff] [blame] | 619 | |
| 620 | ------------------------------------------------- |
| 621 | $ git rev-parse origin |
| 622 | e05db0fd4f31dde7005f075a84f96b360d05984b |
| 623 | ------------------------------------------------- |
| 624 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 625 | [[creating-tags]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 626 | === Creating tags |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 627 | |
| 628 | We can also create a tag to refer to a particular commit; after |
| 629 | running |
| 630 | |
| 631 | ------------------------------------------------- |
Jakub Narebski | 0448352 | 2007-04-03 18:27:28 +0200 | [diff] [blame] | 632 | $ git tag stable-1 1b2e1d63ff |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 633 | ------------------------------------------------- |
| 634 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 635 | You can use `stable-1` to refer to the commit 1b2e1d63ff. |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 636 | |
J. Bruce Fields | c64415e | 2007-05-07 00:56:45 -0400 | [diff] [blame] | 637 | This creates a "lightweight" tag. If you would also like to include a |
| 638 | comment with the tag, and possibly sign it cryptographically, then you |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 639 | should create a tag object instead; see the linkgit:git-tag[1] man page |
J. Bruce Fields | c64415e | 2007-05-07 00:56:45 -0400 | [diff] [blame] | 640 | for details. |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 641 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 642 | [[browsing-revisions]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 643 | === Browsing revisions |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 644 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 645 | The linkgit:git-log[1] command can show lists of commits. On its |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 646 | own, it shows all commits reachable from the parent commit; but you |
| 647 | can also make more specific requests: |
| 648 | |
| 649 | ------------------------------------------------- |
| 650 | $ git log v2.5.. # commits since (not reachable from) v2.5 |
| 651 | $ git log test..master # commits reachable from master but not test |
| 652 | $ git log master..test # ...reachable from test but not master |
| 653 | $ git log master...test # ...reachable from either test or master, |
| 654 | # but not both |
| 655 | $ git log --since="2 weeks ago" # commits from the last 2 weeks |
| 656 | $ git log Makefile # commits which modify Makefile |
| 657 | $ git log fs/ # ... which modify any file under fs/ |
| 658 | $ git log -S'foo()' # commits which add or remove any file data |
| 659 | # matching the string 'foo()' |
| 660 | ------------------------------------------------- |
| 661 | |
| 662 | And of course you can combine all of these; the following finds |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 663 | commits since v2.5 which touch the `Makefile` or any file under `fs`: |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 664 | |
| 665 | ------------------------------------------------- |
| 666 | $ git log v2.5.. Makefile fs/ |
| 667 | ------------------------------------------------- |
| 668 | |
| 669 | You can also ask git log to show patches: |
| 670 | |
| 671 | ------------------------------------------------- |
| 672 | $ git log -p |
| 673 | ------------------------------------------------- |
| 674 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 675 | See the `--pretty` option in the linkgit:git-log[1] man page for more |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 676 | display options. |
| 677 | |
| 678 | Note that git log starts with the most recent commit and works |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 679 | backwards through the parents; however, since Git history can contain |
Pavel Roskin | 3dff537 | 2007-02-03 23:49:16 -0500 | [diff] [blame] | 680 | multiple independent lines of development, the particular order that |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 681 | commits are listed in may be somewhat arbitrary. |
| 682 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 683 | [[generating-diffs]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 684 | === Generating diffs |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 685 | |
| 686 | You can generate diffs between any two versions using |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 687 | linkgit:git-diff[1]: |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 688 | |
| 689 | ------------------------------------------------- |
| 690 | $ git diff master..test |
| 691 | ------------------------------------------------- |
| 692 | |
J. Bruce Fields | 5b98d9b | 2007-11-18 19:18:27 -0500 | [diff] [blame] | 693 | That will produce the diff between the tips of the two branches. If |
| 694 | you'd prefer to find the diff from their common ancestor to test, you |
| 695 | can use three dots instead of two: |
| 696 | |
| 697 | ------------------------------------------------- |
| 698 | $ git diff master...test |
| 699 | ------------------------------------------------- |
| 700 | |
| 701 | Sometimes what you want instead is a set of patches; for this you can |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 702 | use linkgit:git-format-patch[1]: |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 703 | |
| 704 | ------------------------------------------------- |
| 705 | $ git format-patch master..test |
| 706 | ------------------------------------------------- |
| 707 | |
| 708 | will generate a file with a patch for each commit reachable from test |
J. Bruce Fields | 5b98d9b | 2007-11-18 19:18:27 -0500 | [diff] [blame] | 709 | but not from master. |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 710 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 711 | [[viewing-old-file-versions]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 712 | === Viewing old file versions |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 713 | |
| 714 | You can always view an old version of a file by just checking out the |
| 715 | correct revision first. But sometimes it is more convenient to be |
| 716 | able to view an old version of a single file without checking |
| 717 | anything out; this command does that: |
| 718 | |
| 719 | ------------------------------------------------- |
| 720 | $ git show v2.5:fs/locks.c |
| 721 | ------------------------------------------------- |
| 722 | |
| 723 | Before the colon may be anything that names a commit, and after it |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 724 | may be any path to a file tracked by Git. |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 725 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 726 | [[history-examples]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 727 | === Examples |
J. Bruce Fields | aec053b | 2007-01-10 23:17:00 -0500 | [diff] [blame] | 728 | |
J. Bruce Fields | 46acd3f | 2007-05-13 02:14:45 -0400 | [diff] [blame] | 729 | [[counting-commits-on-a-branch]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 730 | ==== Counting the number of commits on a branch |
J. Bruce Fields | 46acd3f | 2007-05-13 02:14:45 -0400 | [diff] [blame] | 731 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 732 | Suppose you want to know how many commits you've made on `mybranch` |
| 733 | since it diverged from `origin`: |
J. Bruce Fields | 46acd3f | 2007-05-13 02:14:45 -0400 | [diff] [blame] | 734 | |
| 735 | ------------------------------------------------- |
| 736 | $ git log --pretty=oneline origin..mybranch | wc -l |
| 737 | ------------------------------------------------- |
| 738 | |
| 739 | Alternatively, you may often see this sort of thing done with the |
Felipe Contreras | a6e5ef7 | 2009-04-04 12:38:27 +0300 | [diff] [blame] | 740 | lower-level command linkgit:git-rev-list[1], which just lists the SHA-1's |
J. Bruce Fields | 46acd3f | 2007-05-13 02:14:45 -0400 | [diff] [blame] | 741 | of all the given commits: |
| 742 | |
| 743 | ------------------------------------------------- |
| 744 | $ git rev-list origin..mybranch | wc -l |
| 745 | ------------------------------------------------- |
| 746 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 747 | [[checking-for-equal-branches]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 748 | ==== Check whether two branches point at the same history |
J. Bruce Fields | aec053b | 2007-01-10 23:17:00 -0500 | [diff] [blame] | 749 | |
| 750 | Suppose you want to check whether two branches point at the same point |
| 751 | in history. |
| 752 | |
| 753 | ------------------------------------------------- |
| 754 | $ git diff origin..master |
| 755 | ------------------------------------------------- |
| 756 | |
J. Bruce Fields | 69f7ad7 | 2007-01-14 16:29:40 -0500 | [diff] [blame] | 757 | will tell you whether the contents of the project are the same at the |
| 758 | two branches; in theory, however, it's possible that the same project |
| 759 | contents could have been arrived at by two different historical |
J. Bruce Fields | d55ae92 | 2007-01-29 02:16:45 -0500 | [diff] [blame] | 760 | routes. You could compare the object names: |
J. Bruce Fields | aec053b | 2007-01-10 23:17:00 -0500 | [diff] [blame] | 761 | |
| 762 | ------------------------------------------------- |
| 763 | $ git rev-list origin |
| 764 | e05db0fd4f31dde7005f075a84f96b360d05984b |
| 765 | $ git rev-list master |
| 766 | e05db0fd4f31dde7005f075a84f96b360d05984b |
| 767 | ------------------------------------------------- |
| 768 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 769 | Or you could recall that the `...` operator selects all commits |
Thomas Ackermann | ddd4dde | 2013-08-27 19:59:21 +0200 | [diff] [blame] | 770 | reachable from either one reference or the other but not |
W. Trevor King | ddd2369 | 2013-02-10 10:10:36 -0500 | [diff] [blame] | 771 | both; so |
J. Bruce Fields | aec053b | 2007-01-10 23:17:00 -0500 | [diff] [blame] | 772 | |
| 773 | ------------------------------------------------- |
| 774 | $ git log origin...master |
| 775 | ------------------------------------------------- |
| 776 | |
| 777 | will return no commits when the two branches are equal. |
| 778 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 779 | [[finding-tagged-descendants]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 780 | ==== Find first tagged version including a given fix |
J. Bruce Fields | aec053b | 2007-01-10 23:17:00 -0500 | [diff] [blame] | 781 | |
J. Bruce Fields | 69f7ad7 | 2007-01-14 16:29:40 -0500 | [diff] [blame] | 782 | Suppose you know that the commit e05db0fd fixed a certain problem. |
| 783 | You'd like to find the earliest tagged release that contains that |
| 784 | fix. |
| 785 | |
| 786 | Of course, there may be more than one answer--if the history branched |
| 787 | after commit e05db0fd, then there could be multiple "earliest" tagged |
| 788 | releases. |
| 789 | |
| 790 | You could just visually inspect the commits since e05db0fd: |
| 791 | |
| 792 | ------------------------------------------------- |
| 793 | $ gitk e05db0fd.. |
| 794 | ------------------------------------------------- |
| 795 | |
Thomas Ackermann | ddd4dde | 2013-08-27 19:59:21 +0200 | [diff] [blame] | 796 | or you can use linkgit:git-name-rev[1], which will give the commit a |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 797 | name based on any tag it finds pointing to one of the commit's |
| 798 | descendants: |
| 799 | |
| 800 | ------------------------------------------------- |
Jakub Narebski | 0448352 | 2007-04-03 18:27:28 +0200 | [diff] [blame] | 801 | $ git name-rev --tags e05db0fd |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 802 | e05db0fd tags/v1.5.0-rc1^0~23 |
| 803 | ------------------------------------------------- |
| 804 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 805 | The linkgit:git-describe[1] command does the opposite, naming the |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 806 | revision using a tag on which the given commit is based: |
| 807 | |
| 808 | ------------------------------------------------- |
| 809 | $ git describe e05db0fd |
Jakub Narebski | 0448352 | 2007-04-03 18:27:28 +0200 | [diff] [blame] | 810 | v1.5.0-rc0-260-ge05db0f |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 811 | ------------------------------------------------- |
| 812 | |
| 813 | but that may sometimes help you guess which tags might come after the |
| 814 | given commit. |
| 815 | |
| 816 | If you just want to verify whether a given tagged version contains a |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 817 | given commit, you could use linkgit:git-merge-base[1]: |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 818 | |
| 819 | ------------------------------------------------- |
| 820 | $ git merge-base e05db0fd v1.5.0-rc1 |
| 821 | e05db0fd4f31dde7005f075a84f96b360d05984b |
| 822 | ------------------------------------------------- |
| 823 | |
| 824 | The merge-base command finds a common ancestor of the given commits, |
| 825 | and always returns one or the other in the case where one is a |
| 826 | descendant of the other; so the above output shows that e05db0fd |
| 827 | actually is an ancestor of v1.5.0-rc1. |
| 828 | |
| 829 | Alternatively, note that |
| 830 | |
| 831 | ------------------------------------------------- |
J. Bruce Fields | 4a7979c | 2007-01-29 01:55:33 -0500 | [diff] [blame] | 832 | $ git log v1.5.0-rc1..e05db0fd |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 833 | ------------------------------------------------- |
| 834 | |
J. Bruce Fields | 4a7979c | 2007-01-29 01:55:33 -0500 | [diff] [blame] | 835 | will produce empty output if and only if v1.5.0-rc1 includes e05db0fd, |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 836 | because it outputs only commits that are not reachable from v1.5.0-rc1. |
J. Bruce Fields | aec053b | 2007-01-10 23:17:00 -0500 | [diff] [blame] | 837 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 838 | As yet another alternative, the linkgit:git-show-branch[1] command lists |
J. Bruce Fields | 4a7979c | 2007-01-29 01:55:33 -0500 | [diff] [blame] | 839 | the commits reachable from its arguments with a display on the left-hand |
Thomas Ackermann | ddd4dde | 2013-08-27 19:59:21 +0200 | [diff] [blame] | 840 | side that indicates which arguments that commit is reachable from. |
| 841 | So, if you run something like |
J. Bruce Fields | 4a7979c | 2007-01-29 01:55:33 -0500 | [diff] [blame] | 842 | |
| 843 | ------------------------------------------------- |
| 844 | $ git show-branch e05db0fd v1.5.0-rc0 v1.5.0-rc1 v1.5.0-rc2 |
| 845 | ! [e05db0fd] Fix warnings in sha1_file.c - use C99 printf format if |
| 846 | available |
| 847 | ! [v1.5.0-rc0] GIT v1.5.0 preview |
| 848 | ! [v1.5.0-rc1] GIT v1.5.0-rc1 |
| 849 | ! [v1.5.0-rc2] GIT v1.5.0-rc2 |
| 850 | ... |
| 851 | ------------------------------------------------- |
| 852 | |
Thomas Ackermann | ddd4dde | 2013-08-27 19:59:21 +0200 | [diff] [blame] | 853 | then a line like |
J. Bruce Fields | 4a7979c | 2007-01-29 01:55:33 -0500 | [diff] [blame] | 854 | |
| 855 | ------------------------------------------------- |
| 856 | + ++ [e05db0fd] Fix warnings in sha1_file.c - use C99 printf format if |
| 857 | available |
| 858 | ------------------------------------------------- |
| 859 | |
Thomas Ackermann | ddd4dde | 2013-08-27 19:59:21 +0200 | [diff] [blame] | 860 | shows that e05db0fd is reachable from itself, from v1.5.0-rc1, |
| 861 | and from v1.5.0-rc2, and not from v1.5.0-rc0. |
J. Bruce Fields | 4a7979c | 2007-01-29 01:55:33 -0500 | [diff] [blame] | 862 | |
J. Bruce Fields | 629d9f7 | 2007-05-13 22:58:06 -0400 | [diff] [blame] | 863 | [[showing-commits-unique-to-a-branch]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 864 | ==== Showing commits unique to a given branch |
J. Bruce Fields | 629d9f7 | 2007-05-13 22:58:06 -0400 | [diff] [blame] | 865 | |
| 866 | Suppose you would like to see all the commits reachable from the branch |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 867 | head named `master` but not from any other head in your repository. |
J. Bruce Fields | 629d9f7 | 2007-05-13 22:58:06 -0400 | [diff] [blame] | 868 | |
| 869 | We can list all the heads in this repository with |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 870 | linkgit:git-show-ref[1]: |
J. Bruce Fields | 629d9f7 | 2007-05-13 22:58:06 -0400 | [diff] [blame] | 871 | |
| 872 | ------------------------------------------------- |
| 873 | $ git show-ref --heads |
| 874 | bf62196b5e363d73353a9dcf094c59595f3153b7 refs/heads/core-tutorial |
| 875 | db768d5504c1bb46f63ee9d6e1772bd047e05bf9 refs/heads/maint |
| 876 | a07157ac624b2524a059a3414e99f6f44bebc1e7 refs/heads/master |
| 877 | 24dbc180ea14dc1aebe09f14c8ecf32010690627 refs/heads/tutorial-2 |
| 878 | 1e87486ae06626c2f31eaa63d26fc0fd646c8af2 refs/heads/tutorial-fixes |
| 879 | ------------------------------------------------- |
| 880 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 881 | We can get just the branch-head names, and remove `master`, with |
J. Bruce Fields | 629d9f7 | 2007-05-13 22:58:06 -0400 | [diff] [blame] | 882 | the help of the standard utilities cut and grep: |
| 883 | |
| 884 | ------------------------------------------------- |
| 885 | $ git show-ref --heads | cut -d' ' -f2 | grep -v '^refs/heads/master' |
| 886 | refs/heads/core-tutorial |
| 887 | refs/heads/maint |
| 888 | refs/heads/tutorial-2 |
| 889 | refs/heads/tutorial-fixes |
| 890 | ------------------------------------------------- |
| 891 | |
| 892 | And then we can ask to see all the commits reachable from master |
| 893 | but not from these other heads: |
| 894 | |
| 895 | ------------------------------------------------- |
| 896 | $ gitk master --not $( git show-ref --heads | cut -d' ' -f2 | |
| 897 | grep -v '^refs/heads/master' ) |
| 898 | ------------------------------------------------- |
| 899 | |
| 900 | Obviously, endless variations are possible; for example, to see all |
| 901 | commits reachable from some head but not from any tag in the repository: |
| 902 | |
| 903 | ------------------------------------------------- |
Steffen Prohaska | c78974f | 2007-05-26 21:16:27 +0200 | [diff] [blame] | 904 | $ gitk $( git show-ref --heads ) --not $( git show-ref --tags ) |
J. Bruce Fields | 629d9f7 | 2007-05-13 22:58:06 -0400 | [diff] [blame] | 905 | ------------------------------------------------- |
| 906 | |
Jonathan Nieder | 9d83e38 | 2010-10-11 11:03:32 -0500 | [diff] [blame] | 907 | (See linkgit:gitrevisions[7] for explanations of commit-selecting |
J. Bruce Fields | 629d9f7 | 2007-05-13 22:58:06 -0400 | [diff] [blame] | 908 | syntax such as `--not`.) |
| 909 | |
J. Bruce Fields | 82c8bf2 | 2007-05-13 00:14:40 -0400 | [diff] [blame] | 910 | [[making-a-release]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 911 | ==== Creating a changelog and tarball for a software release |
J. Bruce Fields | 82c8bf2 | 2007-05-13 00:14:40 -0400 | [diff] [blame] | 912 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 913 | The linkgit:git-archive[1] command can create a tar or zip archive from |
J. Bruce Fields | 82c8bf2 | 2007-05-13 00:14:40 -0400 | [diff] [blame] | 914 | any version of a project; for example: |
| 915 | |
| 916 | ------------------------------------------------- |
W. Trevor King | 7ed1690 | 2013-02-17 19:16:01 -0500 | [diff] [blame] | 917 | $ git archive -o latest.tar.gz --prefix=project/ HEAD |
J. Bruce Fields | 82c8bf2 | 2007-05-13 00:14:40 -0400 | [diff] [blame] | 918 | ------------------------------------------------- |
| 919 | |
W. Trevor King | 7ed1690 | 2013-02-17 19:16:01 -0500 | [diff] [blame] | 920 | will use HEAD to produce a gzipped tar archive in which each filename |
| 921 | is preceded by `project/`. The output file format is inferred from |
| 922 | the output file extension if possible, see linkgit:git-archive[1] for |
| 923 | details. |
| 924 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 925 | Versions of Git older than 1.7.7 don't know about the `tar.gz` format, |
W. Trevor King | 7ed1690 | 2013-02-17 19:16:01 -0500 | [diff] [blame] | 926 | you'll need to use gzip explicitly: |
| 927 | |
| 928 | ------------------------------------------------- |
| 929 | $ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz |
| 930 | ------------------------------------------------- |
J. Bruce Fields | 82c8bf2 | 2007-05-13 00:14:40 -0400 | [diff] [blame] | 931 | |
| 932 | If you're releasing a new version of a software project, you may want |
| 933 | to simultaneously make a changelog to include in the release |
| 934 | announcement. |
| 935 | |
| 936 | Linus Torvalds, for example, makes new kernel releases by tagging them, |
| 937 | then running: |
| 938 | |
| 939 | ------------------------------------------------- |
| 940 | $ release-script 2.6.12 2.6.13-rc6 2.6.13-rc7 |
| 941 | ------------------------------------------------- |
| 942 | |
| 943 | where release-script is a shell script that looks like: |
| 944 | |
| 945 | ------------------------------------------------- |
| 946 | #!/bin/sh |
| 947 | stable="$1" |
| 948 | last="$2" |
| 949 | new="$3" |
| 950 | echo "# git tag v$new" |
| 951 | echo "git archive --prefix=linux-$new/ v$new | gzip -9 > ../linux-$new.tar.gz" |
| 952 | echo "git diff v$stable v$new | gzip -9 > ../patch-$new.gz" |
| 953 | echo "git log --no-merges v$new ^v$last > ../ChangeLog-$new" |
| 954 | echo "git shortlog --no-merges v$new ^v$last > ../ShortLog" |
| 955 | echo "git diff --stat --summary -M v$last v$new > ../diffstat-$new" |
| 956 | ------------------------------------------------- |
| 957 | |
| 958 | and then he just cut-and-pastes the output commands after verifying that |
| 959 | they look OK. |
J. Bruce Fields | 4a7979c | 2007-01-29 01:55:33 -0500 | [diff] [blame] | 960 | |
Michael J Gruber | e1ba4c3 | 2010-09-28 13:16:07 +0200 | [diff] [blame] | 961 | [[Finding-commits-With-given-Content]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 962 | ==== Finding commits referencing a file with given content |
J. Bruce Fields | 187b0d8 | 2007-05-19 00:37:25 -0400 | [diff] [blame] | 963 | |
| 964 | Somebody hands you a copy of a file, and asks which commits modified a |
| 965 | file such that it contained the given content either before or after the |
| 966 | commit. You can find out with this: |
| 967 | |
| 968 | ------------------------------------------------- |
Ralf Wildenhues | 477ff5b | 2007-10-09 23:02:19 +0200 | [diff] [blame] | 969 | $ git log --raw --abbrev=40 --pretty=oneline | |
J. Bruce Fields | 187b0d8 | 2007-05-19 00:37:25 -0400 | [diff] [blame] | 970 | grep -B 1 `git hash-object filename` |
| 971 | ------------------------------------------------- |
| 972 | |
| 973 | Figuring out why this works is left as an exercise to the (advanced) |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 974 | student. The linkgit:git-log[1], linkgit:git-diff-tree[1], and |
| 975 | linkgit:git-hash-object[1] man pages may prove helpful. |
J. Bruce Fields | 187b0d8 | 2007-05-19 00:37:25 -0400 | [diff] [blame] | 976 | |
Junio C Hamano | aa971cb | 2008-12-07 18:38:46 -0800 | [diff] [blame] | 977 | [[Developing-With-git]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 978 | == Developing with Git |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 979 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 980 | [[telling-git-your-name]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 981 | === Telling Git your name |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 982 | |
W. Trevor King | 632cc3e | 2013-02-17 19:15:58 -0500 | [diff] [blame] | 983 | Before creating any commits, you should introduce yourself to Git. |
| 984 | The easiest way to do so is to use linkgit:git-config[1]: |
| 985 | |
| 986 | ------------------------------------------------ |
| 987 | $ git config --global user.name 'Your Name Comes Here' |
| 988 | $ git config --global user.email 'you@yourdomain.example.com' |
| 989 | ------------------------------------------------ |
| 990 | |
| 991 | Which will add the following to a file named `.gitconfig` in your |
| 992 | home directory: |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 993 | |
| 994 | ------------------------------------------------ |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 995 | [user] |
| 996 | name = Your Name Comes Here |
| 997 | email = you@yourdomain.example.com |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 998 | ------------------------------------------------ |
| 999 | |
W. Trevor King | 632cc3e | 2013-02-17 19:15:58 -0500 | [diff] [blame] | 1000 | See the "CONFIGURATION FILE" section of linkgit:git-config[1] for |
| 1001 | details on the configuration file. The file is plain text, so you can |
| 1002 | also edit it with your favorite editor. |
J. Bruce Fields | fc90c53 | 2007-01-29 00:17:51 -0500 | [diff] [blame] | 1003 | |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1004 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 1005 | [[creating-a-new-repository]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 1006 | === Creating a new repository |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1007 | |
| 1008 | Creating a new repository from scratch is very easy: |
| 1009 | |
| 1010 | ------------------------------------------------- |
| 1011 | $ mkdir project |
| 1012 | $ cd project |
J. Bruce Fields | f1d2b47 | 2007-01-11 12:44:08 -0500 | [diff] [blame] | 1013 | $ git init |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1014 | ------------------------------------------------- |
| 1015 | |
| 1016 | If you have some initial content (say, a tarball): |
| 1017 | |
| 1018 | ------------------------------------------------- |
Henrik Austad | 0ddd93b | 2009-01-05 16:25:37 +0100 | [diff] [blame] | 1019 | $ tar xzvf project.tar.gz |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1020 | $ cd project |
J. Bruce Fields | f1d2b47 | 2007-01-11 12:44:08 -0500 | [diff] [blame] | 1021 | $ git init |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1022 | $ git add . # include everything below ./ in the first commit: |
| 1023 | $ git commit |
| 1024 | ------------------------------------------------- |
| 1025 | |
| 1026 | [[how-to-make-a-commit]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 1027 | === How to make a commit |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1028 | |
| 1029 | Creating a new commit takes three steps: |
| 1030 | |
| 1031 | 1. Making some changes to the working directory using your |
| 1032 | favorite editor. |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1033 | 2. Telling Git about your changes. |
| 1034 | 3. Creating the commit using the content you told Git about |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1035 | in step 2. |
| 1036 | |
| 1037 | In practice, you can interleave and repeat steps 1 and 2 as many |
| 1038 | times as you want: in order to keep track of what you want committed |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1039 | at step 3, Git maintains a snapshot of the tree's contents in a |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1040 | special staging area called "the index." |
| 1041 | |
J. Bruce Fields | 01997b4 | 2007-01-10 23:23:37 -0500 | [diff] [blame] | 1042 | At the beginning, the content of the index will be identical to |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 1043 | that of the HEAD. The command `git diff --cached`, which shows |
J. Bruce Fields | 01997b4 | 2007-01-10 23:23:37 -0500 | [diff] [blame] | 1044 | the difference between the HEAD and the index, should therefore |
| 1045 | produce no output at that point. |
Junio C Hamano | eb6ae7f | 2007-01-10 18:11:53 -0800 | [diff] [blame] | 1046 | |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1047 | Modifying the index is easy: |
| 1048 | |
Thomas Ackermann | d39765b | 2013-08-27 20:01:17 +0200 | [diff] [blame] | 1049 | To update the index with the contents of a new or modified file, use |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1050 | |
| 1051 | ------------------------------------------------- |
| 1052 | $ git add path/to/file |
| 1053 | ------------------------------------------------- |
| 1054 | |
Thomas Ackermann | d39765b | 2013-08-27 20:01:17 +0200 | [diff] [blame] | 1055 | To remove a file from the index and from the working tree, use |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1056 | |
| 1057 | ------------------------------------------------- |
| 1058 | $ git rm path/to/file |
| 1059 | ------------------------------------------------- |
| 1060 | |
| 1061 | After each step you can verify that |
| 1062 | |
| 1063 | ------------------------------------------------- |
| 1064 | $ git diff --cached |
| 1065 | ------------------------------------------------- |
| 1066 | |
| 1067 | always shows the difference between the HEAD and the index file--this |
| 1068 | is what you'd commit if you created the commit now--and that |
| 1069 | |
| 1070 | ------------------------------------------------- |
| 1071 | $ git diff |
| 1072 | ------------------------------------------------- |
| 1073 | |
| 1074 | shows the difference between the working tree and the index file. |
| 1075 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 1076 | Note that `git add` always adds just the current contents of a file |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1077 | to the index; further changes to the same file will be ignored unless |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 1078 | you run `git add` on the file again. |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1079 | |
| 1080 | When you're ready, just run |
| 1081 | |
| 1082 | ------------------------------------------------- |
| 1083 | $ git commit |
| 1084 | ------------------------------------------------- |
| 1085 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1086 | and Git will prompt you for a commit message and then create the new |
Pavel Roskin | 3dff537 | 2007-02-03 23:49:16 -0500 | [diff] [blame] | 1087 | commit. Check to make sure it looks like what you expected with |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1088 | |
| 1089 | ------------------------------------------------- |
| 1090 | $ git show |
| 1091 | ------------------------------------------------- |
| 1092 | |
| 1093 | As a special shortcut, |
Junio C Hamano | a6080a0 | 2007-06-07 00:04:01 -0700 | [diff] [blame] | 1094 | |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1095 | ------------------------------------------------- |
| 1096 | $ git commit -a |
| 1097 | ------------------------------------------------- |
| 1098 | |
| 1099 | will update the index with any files that you've modified or removed |
| 1100 | and create a commit, all in one step. |
| 1101 | |
| 1102 | A number of commands are useful for keeping track of what you're |
| 1103 | about to commit: |
| 1104 | |
| 1105 | ------------------------------------------------- |
| 1106 | $ git diff --cached # difference between HEAD and the index; what |
Junio C Hamano | 1130845 | 2007-07-24 01:58:51 -0700 | [diff] [blame] | 1107 | # would be committed if you ran "commit" now. |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1108 | $ git diff # difference between the index file and your |
| 1109 | # working directory; changes that would not |
| 1110 | # be included if you ran "commit" now. |
J. Bruce Fields | c64415e | 2007-05-07 00:56:45 -0400 | [diff] [blame] | 1111 | $ git diff HEAD # difference between HEAD and working tree; what |
| 1112 | # would be committed if you ran "commit -a" now. |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1113 | $ git status # a brief per-file summary of the above. |
| 1114 | ------------------------------------------------- |
| 1115 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 1116 | You can also use linkgit:git-gui[1] to create commits, view changes in |
J. Bruce Fields | 407c0c8 | 2007-08-05 18:12:37 -0400 | [diff] [blame] | 1117 | the index and the working tree files, and individually select diff hunks |
| 1118 | for inclusion in the index (by right-clicking on the diff hunk and |
| 1119 | choosing "Stage Hunk For Commit"). |
| 1120 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 1121 | [[creating-good-commit-messages]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 1122 | === Creating good commit messages |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1123 | |
| 1124 | Though not required, it's a good idea to begin the commit message |
谢致邦 (XIE Zhibang) | 1627e6b | 2023-10-08 15:19:26 +0000 | [diff] [blame] | 1125 | with a single short (no more than 50 characters) line summarizing the |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1126 | change, followed by a blank line and then a more thorough |
Jeremy White | 52ffe99 | 2012-09-13 17:27:09 -0500 | [diff] [blame] | 1127 | description. The text up to the first blank line in a commit |
| 1128 | message is treated as the commit title, and that title is used |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1129 | throughout Git. For example, linkgit:git-format-patch[1] turns a |
Jeremy White | 52ffe99 | 2012-09-13 17:27:09 -0500 | [diff] [blame] | 1130 | commit into email, and it uses the title on the Subject line and the |
| 1131 | rest of the commit in the body. |
| 1132 | |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1133 | |
Johan Herland | 2dc5361 | 2007-05-16 02:31:40 +0200 | [diff] [blame] | 1134 | [[ignoring-files]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 1135 | === Ignoring files |
Johan Herland | 2dc5361 | 2007-05-16 02:31:40 +0200 | [diff] [blame] | 1136 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1137 | A project will often generate files that you do 'not' want to track with Git. |
Johan Herland | 2dc5361 | 2007-05-16 02:31:40 +0200 | [diff] [blame] | 1138 | This typically includes files generated by a build process or temporary |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1139 | backup files made by your editor. Of course, 'not' tracking files with Git |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 1140 | is just a matter of 'not' calling `git add` on them. But it quickly becomes |
Johan Herland | 2dc5361 | 2007-05-16 02:31:40 +0200 | [diff] [blame] | 1141 | annoying to have these untracked files lying around; e.g. they make |
Chris Johnsen | dcb1126 | 2009-03-15 06:30:52 -0500 | [diff] [blame] | 1142 | `git add .` practically useless, and they keep showing up in the output of |
| 1143 | `git status`. |
Johan Herland | 2dc5361 | 2007-05-16 02:31:40 +0200 | [diff] [blame] | 1144 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 1145 | You can tell Git to ignore certain files by creating a file called |
| 1146 | `.gitignore` in the top level of your working directory, with contents |
| 1147 | such as: |
Johan Herland | 2dc5361 | 2007-05-16 02:31:40 +0200 | [diff] [blame] | 1148 | |
| 1149 | ------------------------------------------------- |
| 1150 | # Lines starting with '#' are considered comments. |
J. Bruce Fields | 464a8a7 | 2007-05-24 20:28:14 -0400 | [diff] [blame] | 1151 | # Ignore any file named foo.txt. |
Johan Herland | 2dc5361 | 2007-05-16 02:31:40 +0200 | [diff] [blame] | 1152 | foo.txt |
| 1153 | # Ignore (generated) html files, |
| 1154 | *.html |
| 1155 | # except foo.html which is maintained by hand. |
| 1156 | !foo.html |
| 1157 | # Ignore objects and archives. |
| 1158 | *.[oa] |
| 1159 | ------------------------------------------------- |
| 1160 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 1161 | See linkgit:gitignore[5] for a detailed explanation of the syntax. You can |
J. Bruce Fields | 464a8a7 | 2007-05-24 20:28:14 -0400 | [diff] [blame] | 1162 | also place .gitignore files in other directories in your working tree, and they |
| 1163 | will apply to those directories and their subdirectories. The `.gitignore` |
| 1164 | files can be added to your repository like any other files (just run `git add |
| 1165 | .gitignore` and `git commit`, as usual), which is convenient when the exclude |
| 1166 | patterns (such as patterns matching build output files) would also make sense |
| 1167 | for other users who clone your repository. |
Johan Herland | 2dc5361 | 2007-05-16 02:31:40 +0200 | [diff] [blame] | 1168 | |
J. Bruce Fields | 464a8a7 | 2007-05-24 20:28:14 -0400 | [diff] [blame] | 1169 | If you wish the exclude patterns to affect only certain repositories |
| 1170 | (instead of every repository for a given project), you may instead put |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 1171 | them in a file in your repository named `.git/info/exclude`, or in any |
Nguyễn Thái Ngọc Duy | da0005b | 2015-03-11 16:32:45 -0400 | [diff] [blame] | 1172 | file specified by the `core.excludesFile` configuration variable. |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 1173 | Some Git commands can also take exclude patterns directly on the |
| 1174 | command line. See linkgit:gitignore[5] for the details. |
Johan Herland | 2dc5361 | 2007-05-16 02:31:40 +0200 | [diff] [blame] | 1175 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 1176 | [[how-to-merge]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 1177 | === How to merge |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1178 | |
| 1179 | You can rejoin two diverging branches of development using |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 1180 | linkgit:git-merge[1]: |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1181 | |
| 1182 | ------------------------------------------------- |
| 1183 | $ git merge branchname |
| 1184 | ------------------------------------------------- |
| 1185 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 1186 | merges the development in the branch `branchname` into the current |
Matthieu Moy | e63ec00 | 2009-11-22 23:26:18 +0100 | [diff] [blame] | 1187 | branch. |
| 1188 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 1189 | A merge is made by combining the changes made in `branchname` and the |
Matthieu Moy | e63ec00 | 2009-11-22 23:26:18 +0100 | [diff] [blame] | 1190 | changes made up to the latest commit in your current branch since |
| 1191 | their histories forked. The work tree is overwritten by the result of |
| 1192 | the merge when this combining is done cleanly, or overwritten by a |
| 1193 | half-merged results when this combining results in conflicts. |
| 1194 | Therefore, if you have uncommitted changes touching the same files as |
| 1195 | the ones impacted by the merge, Git will refuse to proceed. Most of |
| 1196 | the time, you will want to commit your changes before you can merge, |
| 1197 | and if you don't, then linkgit:git-stash[1] can take these changes |
| 1198 | away while you're doing the merge, and reapply them afterwards. |
| 1199 | |
Ralf Wildenhues | 6a5d0b0 | 2010-01-31 14:24:39 +0100 | [diff] [blame] | 1200 | If the changes are independent enough, Git will automatically complete |
Matthieu Moy | e63ec00 | 2009-11-22 23:26:18 +0100 | [diff] [blame] | 1201 | the merge and commit the result (or reuse an existing commit in case |
| 1202 | of <<fast-forwards,fast-forward>>, see below). On the other hand, |
| 1203 | if there are conflicts--for example, if the same file is |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1204 | modified in two different ways in the remote branch and the local |
| 1205 | branch--then you are warned; the output may look something like this: |
| 1206 | |
| 1207 | ------------------------------------------------- |
J. Bruce Fields | fabbd8f | 2007-03-10 21:52:39 -0500 | [diff] [blame] | 1208 | $ git merge next |
| 1209 | 100% (4/4) done |
| 1210 | Auto-merged file.txt |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1211 | CONFLICT (content): Merge conflict in file.txt |
| 1212 | Automatic merge failed; fix conflicts and then commit the result. |
| 1213 | ------------------------------------------------- |
| 1214 | |
| 1215 | Conflict markers are left in the problematic files, and after |
| 1216 | you resolve the conflicts manually, you can update the index |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1217 | with the contents and run Git commit, as you normally would when |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1218 | creating a new file. |
| 1219 | |
| 1220 | If you examine the resulting commit using gitk, you will see that it |
| 1221 | has two parents, one pointing to the top of the current branch, and |
| 1222 | one to the top of the other branch. |
| 1223 | |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1224 | [[resolving-a-merge]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 1225 | === Resolving a merge |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1226 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1227 | When a merge isn't resolved automatically, Git leaves the index and |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1228 | the working tree in a special state that gives you all the |
| 1229 | information you need to help resolve the merge. |
| 1230 | |
| 1231 | Files with conflicts are marked specially in the index, so until you |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 1232 | resolve the problem and update the index, linkgit:git-commit[1] will |
J. Bruce Fields | ef561ac | 2007-03-03 15:34:27 -0500 | [diff] [blame] | 1233 | fail: |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1234 | |
| 1235 | ------------------------------------------------- |
| 1236 | $ git commit |
| 1237 | file.txt: needs merge |
| 1238 | ------------------------------------------------- |
| 1239 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 1240 | Also, linkgit:git-status[1] will list those files as "unmerged", and the |
J. Bruce Fields | ef561ac | 2007-03-03 15:34:27 -0500 | [diff] [blame] | 1241 | files with conflicts will have conflict markers added, like this: |
| 1242 | |
| 1243 | ------------------------------------------------- |
| 1244 | <<<<<<< HEAD:file.txt |
| 1245 | Hello world |
| 1246 | ======= |
| 1247 | Goodbye |
| 1248 | >>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt |
| 1249 | ------------------------------------------------- |
| 1250 | |
| 1251 | All you need to do is edit the files to resolve the conflicts, and then |
| 1252 | |
| 1253 | ------------------------------------------------- |
| 1254 | $ git add file.txt |
| 1255 | $ git commit |
| 1256 | ------------------------------------------------- |
| 1257 | |
| 1258 | Note that the commit message will already be filled in for you with |
| 1259 | some information about the merge. Normally you can just use this |
| 1260 | default message unchanged, but you may add additional commentary of |
| 1261 | your own if desired. |
| 1262 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1263 | The above is all you need to know to resolve a simple merge. But Git |
J. Bruce Fields | ef561ac | 2007-03-03 15:34:27 -0500 | [diff] [blame] | 1264 | also provides more information to help resolve conflicts: |
| 1265 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 1266 | [[conflict-resolution]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 1267 | ==== Getting conflict-resolution help during a merge |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1268 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1269 | All of the changes that Git was able to merge automatically are |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 1270 | already added to the index file, so linkgit:git-diff[1] shows only |
J. Bruce Fields | ef561ac | 2007-03-03 15:34:27 -0500 | [diff] [blame] | 1271 | the conflicts. It uses an unusual syntax: |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1272 | |
| 1273 | ------------------------------------------------- |
| 1274 | $ git diff |
| 1275 | diff --cc file.txt |
| 1276 | index 802992c,2b60207..0000000 |
| 1277 | --- a/file.txt |
| 1278 | +++ b/file.txt |
| 1279 | @@@ -1,1 -1,1 +1,5 @@@ |
| 1280 | ++<<<<<<< HEAD:file.txt |
| 1281 | +Hello world |
| 1282 | ++======= |
| 1283 | + Goodbye |
| 1284 | ++>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt |
| 1285 | ------------------------------------------------- |
| 1286 | |
Junio C Hamano | 1130845 | 2007-07-24 01:58:51 -0700 | [diff] [blame] | 1287 | Recall that the commit which will be committed after we resolve this |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1288 | conflict will have two parents instead of the usual one: one parent |
| 1289 | will be HEAD, the tip of the current branch; the other will be the |
| 1290 | tip of the other branch, which is stored temporarily in MERGE_HEAD. |
| 1291 | |
J. Bruce Fields | ef561ac | 2007-03-03 15:34:27 -0500 | [diff] [blame] | 1292 | During the merge, the index holds three versions of each file. Each of |
| 1293 | these three "file stages" represents a different version of the file: |
| 1294 | |
| 1295 | ------------------------------------------------- |
| 1296 | $ git show :1:file.txt # the file in a common ancestor of both branches |
Junio C Hamano | 4209752 | 2008-06-12 14:30:37 -0700 | [diff] [blame] | 1297 | $ git show :2:file.txt # the version from HEAD. |
| 1298 | $ git show :3:file.txt # the version from MERGE_HEAD. |
J. Bruce Fields | ef561ac | 2007-03-03 15:34:27 -0500 | [diff] [blame] | 1299 | ------------------------------------------------- |
| 1300 | |
Junio C Hamano | 4209752 | 2008-06-12 14:30:37 -0700 | [diff] [blame] | 1301 | When you ask linkgit:git-diff[1] to show the conflicts, it runs a |
| 1302 | three-way diff between the conflicted merge results in the work tree with |
| 1303 | stages 2 and 3 to show only hunks whose contents come from both sides, |
| 1304 | mixed (in other words, when a hunk's merge results come only from stage 2, |
| 1305 | that part is not conflicting and is not shown. Same for stage 3). |
J. Bruce Fields | ef561ac | 2007-03-03 15:34:27 -0500 | [diff] [blame] | 1306 | |
| 1307 | The diff above shows the differences between the working-tree version of |
| 1308 | file.txt and the stage 2 and stage 3 versions. So instead of preceding |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 1309 | each line by a single `+` or `-`, it now uses two columns: the first |
J. Bruce Fields | ef561ac | 2007-03-03 15:34:27 -0500 | [diff] [blame] | 1310 | column is used for differences between the first parent and the working |
| 1311 | directory copy, and the second for differences between the second parent |
| 1312 | and the working directory copy. (See the "COMBINED DIFF FORMAT" section |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 1313 | of linkgit:git-diff-files[1] for a details of the format.) |
J. Bruce Fields | ef561ac | 2007-03-03 15:34:27 -0500 | [diff] [blame] | 1314 | |
| 1315 | After resolving the conflict in the obvious way (but before updating the |
| 1316 | index), the diff will look like: |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1317 | |
| 1318 | ------------------------------------------------- |
| 1319 | $ git diff |
| 1320 | diff --cc file.txt |
| 1321 | index 802992c,2b60207..0000000 |
| 1322 | --- a/file.txt |
| 1323 | +++ b/file.txt |
| 1324 | @@@ -1,1 -1,1 +1,1 @@@ |
| 1325 | - Hello world |
| 1326 | -Goodbye |
| 1327 | ++Goodbye world |
| 1328 | ------------------------------------------------- |
| 1329 | |
| 1330 | This shows that our resolved version deleted "Hello world" from the |
| 1331 | first parent, deleted "Goodbye" from the second parent, and added |
| 1332 | "Goodbye world", which was previously absent from both. |
| 1333 | |
J. Bruce Fields | ef561ac | 2007-03-03 15:34:27 -0500 | [diff] [blame] | 1334 | Some special diff options allow diffing the working directory against |
| 1335 | any of these stages: |
| 1336 | |
| 1337 | ------------------------------------------------- |
| 1338 | $ git diff -1 file.txt # diff against stage 1 |
| 1339 | $ git diff --base file.txt # same as the above |
| 1340 | $ git diff -2 file.txt # diff against stage 2 |
| 1341 | $ git diff --ours file.txt # same as the above |
| 1342 | $ git diff -3 file.txt # diff against stage 3 |
| 1343 | $ git diff --theirs file.txt # same as the above. |
| 1344 | ------------------------------------------------- |
| 1345 | |
Philippe Blain | 4fa1edb | 2023-05-22 19:29:00 +0000 | [diff] [blame] | 1346 | When using the 'ort' merge strategy (the default), before updating the working |
Junio C Hamano | dada386 | 2023-12-15 12:32:44 -0800 | [diff] [blame] | 1347 | tree with the result of the merge, Git writes a ref named AUTO_MERGE |
Philippe Blain | 4fa1edb | 2023-05-22 19:29:00 +0000 | [diff] [blame] | 1348 | reflecting the state of the tree it is about to write. Conflicted paths with |
| 1349 | textual conflicts that could not be automatically merged are written to this |
| 1350 | tree with conflict markers, just as in the working tree. AUTO_MERGE can thus be |
| 1351 | used with linkgit:git-diff[1] to show the changes you've made so far to resolve |
| 1352 | conflicts. Using the same example as above, after resolving the conflict we |
| 1353 | get: |
| 1354 | |
| 1355 | ------------------------------------------------- |
| 1356 | $ git diff AUTO_MERGE |
| 1357 | diff --git a/file.txt b/file.txt |
| 1358 | index cd10406..8bf5ae7 100644 |
| 1359 | --- a/file.txt |
| 1360 | +++ b/file.txt |
| 1361 | @@ -1,5 +1 @@ |
| 1362 | -<<<<<<< HEAD:file.txt |
| 1363 | -Hello world |
| 1364 | -======= |
| 1365 | -Goodbye |
| 1366 | ->>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt |
| 1367 | +Goodbye world |
| 1368 | ------------------------------------------------- |
| 1369 | |
| 1370 | Notice that the diff shows we deleted the conflict markers and both versions of |
| 1371 | the content line, and wrote "Goodbye world" instead. |
| 1372 | |
Jonathan Nieder | 0cafe94 | 2008-07-02 23:54:38 -0500 | [diff] [blame] | 1373 | The linkgit:git-log[1] and linkgit:gitk[1] commands also provide special help |
J. Bruce Fields | ef561ac | 2007-03-03 15:34:27 -0500 | [diff] [blame] | 1374 | for merges: |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1375 | |
| 1376 | ------------------------------------------------- |
| 1377 | $ git log --merge |
J. Bruce Fields | ef561ac | 2007-03-03 15:34:27 -0500 | [diff] [blame] | 1378 | $ gitk --merge |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1379 | ------------------------------------------------- |
| 1380 | |
J. Bruce Fields | ef561ac | 2007-03-03 15:34:27 -0500 | [diff] [blame] | 1381 | These will display all commits which exist only on HEAD or on |
| 1382 | MERGE_HEAD, and which touch an unmerged file. |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1383 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 1384 | You may also use linkgit:git-mergetool[1], which lets you merge the |
Henrik Austad | c7719fb | 2009-01-05 16:25:36 +0100 | [diff] [blame] | 1385 | unmerged files using external tools such as Emacs or kdiff3. |
J. Bruce Fields | c64415e | 2007-05-07 00:56:45 -0400 | [diff] [blame] | 1386 | |
J. Bruce Fields | ef561ac | 2007-03-03 15:34:27 -0500 | [diff] [blame] | 1387 | Each time you resolve the conflicts in a file and update the index: |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1388 | |
| 1389 | ------------------------------------------------- |
| 1390 | $ git add file.txt |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1391 | ------------------------------------------------- |
| 1392 | |
J. Bruce Fields | ef561ac | 2007-03-03 15:34:27 -0500 | [diff] [blame] | 1393 | the different stages of that file will be "collapsed", after which |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 1394 | `git diff` will (by default) no longer show diffs for that file. |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1395 | |
| 1396 | [[undoing-a-merge]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 1397 | === Undoing a merge |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1398 | |
| 1399 | If you get stuck and decide to just give up and throw the whole mess |
| 1400 | away, you can always return to the pre-merge state with |
| 1401 | |
| 1402 | ------------------------------------------------- |
Nguyễn Thái Ngọc Duy | fc991b4 | 2019-04-25 16:45:57 +0700 | [diff] [blame] | 1403 | $ git merge --abort |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1404 | ------------------------------------------------- |
| 1405 | |
Junio C Hamano | 1130845 | 2007-07-24 01:58:51 -0700 | [diff] [blame] | 1406 | Or, if you've already committed the merge that you want to throw away, |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1407 | |
| 1408 | ------------------------------------------------- |
J. Bruce Fields | 1c73bb0 | 2007-02-19 18:46:09 -0500 | [diff] [blame] | 1409 | $ git reset --hard ORIG_HEAD |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1410 | ------------------------------------------------- |
| 1411 | |
| 1412 | However, this last command can be dangerous in some cases--never |
| 1413 | throw away a commit you have already committed if that commit may |
| 1414 | itself have been merged into another branch, as doing so may confuse |
| 1415 | further merges. |
| 1416 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 1417 | [[fast-forwards]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 1418 | === Fast-forward merges |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1419 | |
| 1420 | There is one special case not mentioned above, which is treated |
| 1421 | differently. Normally, a merge results in a merge commit, with two |
| 1422 | parents, one pointing at each of the two lines of development that |
| 1423 | were merged. |
| 1424 | |
Xue Fuqiao | b2af482 | 2015-10-25 08:28:43 +0800 | [diff] [blame] | 1425 | However, if the current branch is an ancestor of the other--so every commit |
| 1426 | present in the current branch is already contained in the other branch--then Git |
| 1427 | just performs a "fast-forward"; the head of the current branch is moved forward |
| 1428 | to point at the head of the merged-in branch, without any new commits being |
| 1429 | created. |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1430 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 1431 | [[fixing-mistakes]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 1432 | === Fixing mistakes |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1433 | |
| 1434 | If you've messed up the working tree, but haven't yet committed your |
| 1435 | mistake, you can return the entire working tree to the last committed |
| 1436 | state with |
| 1437 | |
| 1438 | ------------------------------------------------- |
Nguyễn Thái Ngọc Duy | 80f537f | 2019-04-25 16:45:58 +0700 | [diff] [blame] | 1439 | $ git restore --staged --worktree :/ |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1440 | ------------------------------------------------- |
| 1441 | |
| 1442 | If you make a commit that you later wish you hadn't, there are two |
| 1443 | fundamentally different ways to fix the problem: |
| 1444 | |
| 1445 | 1. You can create a new commit that undoes whatever was done |
Sergei Organov | 93cbbd7 | 2007-11-14 12:08:15 -0800 | [diff] [blame] | 1446 | by the old commit. This is the correct thing if your |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1447 | mistake has already been made public. |
| 1448 | |
| 1449 | 2. You can go back and modify the old commit. You should |
| 1450 | never do this if you have already made the history public; |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1451 | Git does not normally expect the "history" of a project to |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1452 | change, and cannot correctly perform repeated merges from |
| 1453 | a branch that has had its history changed. |
| 1454 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 1455 | [[reverting-a-commit]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 1456 | ==== Fixing a mistake with a new commit |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1457 | |
| 1458 | Creating a new commit that reverts an earlier change is very easy; |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 1459 | just pass the linkgit:git-revert[1] command a reference to the bad |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1460 | commit; for example, to revert the most recent commit: |
| 1461 | |
| 1462 | ------------------------------------------------- |
| 1463 | $ git revert HEAD |
| 1464 | ------------------------------------------------- |
| 1465 | |
| 1466 | This will create a new commit which undoes the change in HEAD. You |
| 1467 | will be given a chance to edit the commit message for the new commit. |
| 1468 | |
| 1469 | You can also revert an earlier change, for example, the next-to-last: |
| 1470 | |
| 1471 | ------------------------------------------------- |
| 1472 | $ git revert HEAD^ |
| 1473 | ------------------------------------------------- |
| 1474 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1475 | In this case Git will attempt to undo the old change while leaving |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1476 | intact any changes made since then. If more recent changes overlap |
| 1477 | with the changes to be reverted, then you will be asked to fix |
| 1478 | conflicts manually, just as in the case of <<resolving-a-merge, |
| 1479 | resolving a merge>>. |
| 1480 | |
J. Bruce Fields | 7cb192e | 2007-11-25 19:01:57 -0500 | [diff] [blame] | 1481 | [[fixing-a-mistake-by-rewriting-history]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 1482 | ==== Fixing a mistake by rewriting history |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1483 | |
| 1484 | If the problematic commit is the most recent commit, and you have not |
| 1485 | yet made that commit public, then you may just |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 1486 | <<undoing-a-merge,destroy it using `git reset`>>. |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1487 | |
| 1488 | Alternatively, you |
| 1489 | can edit the working directory and update the index to fix your |
| 1490 | mistake, just as if you were going to <<how-to-make-a-commit,create a |
| 1491 | new commit>>, then run |
| 1492 | |
| 1493 | ------------------------------------------------- |
| 1494 | $ git commit --amend |
| 1495 | ------------------------------------------------- |
| 1496 | |
| 1497 | which will replace the old commit by a new commit incorporating your |
| 1498 | changes, giving you a chance to edit the old commit message first. |
| 1499 | |
| 1500 | Again, you should never do this to a commit that may already have |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 1501 | been merged into another branch; use linkgit:git-revert[1] instead in |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1502 | that case. |
| 1503 | |
J. Bruce Fields | 7cb192e | 2007-11-25 19:01:57 -0500 | [diff] [blame] | 1504 | It is also possible to replace commits further back in the history, but |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1505 | this is an advanced topic to be left for |
| 1506 | <<cleaning-up-history,another chapter>>. |
| 1507 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 1508 | [[checkout-of-path]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 1509 | ==== Checking out an old version of a file |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1510 | |
| 1511 | In the process of undoing a previous bad change, you may find it |
| 1512 | useful to check out an older version of a particular file using |
Nguyễn Thái Ngọc Duy | 80f537f | 2019-04-25 16:45:58 +0700 | [diff] [blame] | 1513 | linkgit:git-restore[1]. The command |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1514 | |
| 1515 | ------------------------------------------------- |
Nguyễn Thái Ngọc Duy | 80f537f | 2019-04-25 16:45:58 +0700 | [diff] [blame] | 1516 | $ git restore --source=HEAD^ path/to/file |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1517 | ------------------------------------------------- |
| 1518 | |
| 1519 | replaces path/to/file by the contents it had in the commit HEAD^, and |
| 1520 | also updates the index to match. It does not change branches. |
| 1521 | |
| 1522 | If you just want to look at an old version of the file, without |
| 1523 | modifying the working directory, you can do that with |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 1524 | linkgit:git-show[1]: |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1525 | |
| 1526 | ------------------------------------------------- |
J. Bruce Fields | ed4eb0d | 2007-03-10 22:00:12 -0500 | [diff] [blame] | 1527 | $ git show HEAD^:path/to/file |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 1528 | ------------------------------------------------- |
| 1529 | |
| 1530 | which will display the given version of the file. |
| 1531 | |
Junio C Hamano | 7a7cc59 | 2007-08-03 15:22:59 -0700 | [diff] [blame] | 1532 | [[interrupted-work]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 1533 | ==== Temporarily setting aside work in progress |
Junio C Hamano | 7a7cc59 | 2007-08-03 15:22:59 -0700 | [diff] [blame] | 1534 | |
| 1535 | While you are in the middle of working on something complicated, you |
| 1536 | find an unrelated but obvious and trivial bug. You would like to fix it |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 1537 | before continuing. You can use linkgit:git-stash[1] to save the current |
Junio C Hamano | 7a7cc59 | 2007-08-03 15:22:59 -0700 | [diff] [blame] | 1538 | state of your work, and after fixing the bug (or, optionally after doing |
| 1539 | so on a different branch and then coming back), unstash the |
| 1540 | work-in-progress changes. |
| 1541 | |
| 1542 | ------------------------------------------------ |
Thomas Gummerer | db37745 | 2017-10-22 18:04:07 +0100 | [diff] [blame] | 1543 | $ git stash push -m "work in progress for foo feature" |
Junio C Hamano | 7a7cc59 | 2007-08-03 15:22:59 -0700 | [diff] [blame] | 1544 | ------------------------------------------------ |
| 1545 | |
| 1546 | This command will save your changes away to the `stash`, and |
| 1547 | reset your working tree and the index to match the tip of your |
| 1548 | current branch. Then you can make your fix as usual. |
| 1549 | |
| 1550 | ------------------------------------------------ |
| 1551 | ... edit and test ... |
| 1552 | $ git commit -a -m "blorpl: typofix" |
| 1553 | ------------------------------------------------ |
| 1554 | |
| 1555 | After that, you can go back to what you were working on with |
Thomas Rast | 7b8988e | 2009-05-28 11:40:15 +0200 | [diff] [blame] | 1556 | `git stash pop`: |
Junio C Hamano | 7a7cc59 | 2007-08-03 15:22:59 -0700 | [diff] [blame] | 1557 | |
| 1558 | ------------------------------------------------ |
Thomas Rast | 7b8988e | 2009-05-28 11:40:15 +0200 | [diff] [blame] | 1559 | $ git stash pop |
Junio C Hamano | 7a7cc59 | 2007-08-03 15:22:59 -0700 | [diff] [blame] | 1560 | ------------------------------------------------ |
| 1561 | |
| 1562 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 1563 | [[ensuring-good-performance]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 1564 | === Ensuring good performance |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1565 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1566 | On large repositories, Git depends on compression to keep the history |
W. Trevor King | 901fd18 | 2013-02-10 10:10:27 -0500 | [diff] [blame] | 1567 | information from taking up too much space on disk or in memory. Some |
Junio C Hamano | e1ebf21 | 2013-02-10 20:40:44 -0800 | [diff] [blame] | 1568 | Git commands may automatically run linkgit:git-gc[1], so you don't |
W. Trevor King | 901fd18 | 2013-02-10 10:10:27 -0500 | [diff] [blame] | 1569 | have to worry about running it manually. However, compressing a large |
| 1570 | repository may take a while, so you may want to call `gc` explicitly |
| 1571 | to avoid automatic compression kicking in when it is not convenient. |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1572 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 1573 | |
| 1574 | [[ensuring-reliability]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 1575 | === Ensuring reliability |
J. Bruce Fields | 11e016a | 2007-01-26 00:17:12 -0500 | [diff] [blame] | 1576 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 1577 | [[checking-for-corruption]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 1578 | ==== Checking the repository for corruption |
J. Bruce Fields | 11e016a | 2007-01-26 00:17:12 -0500 | [diff] [blame] | 1579 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 1580 | The linkgit:git-fsck[1] command runs a number of self-consistency checks |
J. Bruce Fields | 1191ee1 | 2007-01-29 01:33:55 -0500 | [diff] [blame] | 1581 | on the repository, and reports on any problems. This may take some |
Junio C Hamano | c6a13b2 | 2012-02-28 14:55:39 -0800 | [diff] [blame] | 1582 | time. |
J. Bruce Fields | 21dcb3b | 2007-01-28 23:29:19 -0500 | [diff] [blame] | 1583 | |
| 1584 | ------------------------------------------------- |
J. Bruce Fields | 04e50e9 | 2007-01-28 23:31:47 -0500 | [diff] [blame] | 1585 | $ git fsck |
J. Bruce Fields | 21dcb3b | 2007-01-28 23:29:19 -0500 | [diff] [blame] | 1586 | dangling commit 7281251ddd2a61e38657c827739c57015671a6b3 |
| 1587 | dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a63 |
| 1588 | dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b5 |
| 1589 | dangling blob 218761f9d90712d37a9c5e36f406f92202db07eb |
| 1590 | dangling commit bf093535a34a4d35731aa2bd90fe6b176302f14f |
| 1591 | dangling commit 8e4bec7f2ddaa268bef999853c25755452100f8e |
| 1592 | dangling tree d50bb86186bf27b681d25af89d3b5b68382e4085 |
| 1593 | dangling tree b24c2473f1fd3d91352a624795be026d64c8841f |
| 1594 | ... |
| 1595 | ------------------------------------------------- |
| 1596 | |
Junio C Hamano | c6a13b2 | 2012-02-28 14:55:39 -0800 | [diff] [blame] | 1597 | You will see informational messages on dangling objects. They are objects |
| 1598 | that still exist in the repository but are no longer referenced by any of |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 1599 | your branches, and can (and will) be removed after a while with `gc`. |
Miklos Vajna | b4ab198 | 2012-06-19 19:56:09 +0200 | [diff] [blame] | 1600 | You can run `git fsck --no-dangling` to suppress these messages, and still |
Junio C Hamano | c6a13b2 | 2012-02-28 14:55:39 -0800 | [diff] [blame] | 1601 | view real errors. |
J. Bruce Fields | 1cdade2 | 2007-03-03 22:53:37 -0500 | [diff] [blame] | 1602 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 1603 | [[recovering-lost-changes]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 1604 | ==== Recovering lost changes |
J. Bruce Fields | 11e016a | 2007-01-26 00:17:12 -0500 | [diff] [blame] | 1605 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 1606 | [[reflogs]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 1607 | ===== Reflogs |
J. Bruce Fields | 559e4d7 | 2007-01-29 01:31:35 -0500 | [diff] [blame] | 1608 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 1609 | Say you modify a branch with <<fixing-mistakes,`git reset --hard`>>, |
| 1610 | and then realize that the branch was the only reference you had to |
| 1611 | that point in history. |
J. Bruce Fields | 559e4d7 | 2007-01-29 01:31:35 -0500 | [diff] [blame] | 1612 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1613 | Fortunately, Git also keeps a log, called a "reflog", of all the |
J. Bruce Fields | 559e4d7 | 2007-01-29 01:31:35 -0500 | [diff] [blame] | 1614 | previous values of each branch. So in this case you can still find the |
Junio C Hamano | a6080a0 | 2007-06-07 00:04:01 -0700 | [diff] [blame] | 1615 | old history using, for example, |
J. Bruce Fields | 559e4d7 | 2007-01-29 01:31:35 -0500 | [diff] [blame] | 1616 | |
| 1617 | ------------------------------------------------- |
| 1618 | $ git log master@{1} |
| 1619 | ------------------------------------------------- |
| 1620 | |
Sergei Organov | e502c2c | 2007-11-16 14:28:57 +0300 | [diff] [blame] | 1621 | This lists the commits reachable from the previous version of the |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 1622 | `master` branch head. This syntax can be used with any Git command |
| 1623 | that accepts a commit, not just with `git log`. Some other examples: |
J. Bruce Fields | 559e4d7 | 2007-01-29 01:31:35 -0500 | [diff] [blame] | 1624 | |
| 1625 | ------------------------------------------------- |
| 1626 | $ git show master@{2} # See where the branch pointed 2, |
| 1627 | $ git show master@{3} # 3, ... changes ago. |
| 1628 | $ gitk master@{yesterday} # See where it pointed yesterday, |
| 1629 | $ gitk master@{"1 week ago"} # ... or last week |
J. Bruce Fields | 953f3d6 | 2007-04-18 00:20:46 -0400 | [diff] [blame] | 1630 | $ git log --walk-reflogs master # show reflog entries for master |
J. Bruce Fields | 559e4d7 | 2007-01-29 01:31:35 -0500 | [diff] [blame] | 1631 | ------------------------------------------------- |
| 1632 | |
J. Bruce Fields | 953f3d6 | 2007-04-18 00:20:46 -0400 | [diff] [blame] | 1633 | A separate reflog is kept for the HEAD, so |
| 1634 | |
| 1635 | ------------------------------------------------- |
| 1636 | $ git show HEAD@{"1 week ago"} |
| 1637 | ------------------------------------------------- |
| 1638 | |
| 1639 | will show what HEAD pointed to one week ago, not what the current branch |
| 1640 | pointed to one week ago. This allows you to see the history of what |
| 1641 | you've checked out. |
| 1642 | |
J. Bruce Fields | 559e4d7 | 2007-01-29 01:31:35 -0500 | [diff] [blame] | 1643 | The reflogs are kept by default for 30 days, after which they may be |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 1644 | pruned. See linkgit:git-reflog[1] and linkgit:git-gc[1] to learn |
J. Bruce Fields | 559e4d7 | 2007-01-29 01:31:35 -0500 | [diff] [blame] | 1645 | how to control this pruning, and see the "SPECIFYING REVISIONS" |
Jonathan Nieder | 9d83e38 | 2010-10-11 11:03:32 -0500 | [diff] [blame] | 1646 | section of linkgit:gitrevisions[7] for details. |
J. Bruce Fields | 559e4d7 | 2007-01-29 01:31:35 -0500 | [diff] [blame] | 1647 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1648 | Note that the reflog history is very different from normal Git history. |
J. Bruce Fields | 559e4d7 | 2007-01-29 01:31:35 -0500 | [diff] [blame] | 1649 | While normal history is shared by every repository that works on the |
| 1650 | same project, the reflog history is not shared: it tells you only about |
| 1651 | how the branches in your local repository have changed over time. |
| 1652 | |
J. Bruce Fields | 5972304 | 2007-04-30 11:11:02 -0400 | [diff] [blame] | 1653 | [[dangling-object-recovery]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 1654 | ===== Examining dangling objects |
J. Bruce Fields | 559e4d7 | 2007-01-29 01:31:35 -0500 | [diff] [blame] | 1655 | |
J. Bruce Fields | 5972304 | 2007-04-30 11:11:02 -0400 | [diff] [blame] | 1656 | In some situations the reflog may not be able to save you. For example, |
| 1657 | suppose you delete a branch, then realize you need the history it |
| 1658 | contained. The reflog is also deleted; however, if you have not yet |
| 1659 | pruned the repository, then you may still be able to find the lost |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 1660 | commits in the dangling objects that `git fsck` reports. See |
J. Bruce Fields | 5972304 | 2007-04-30 11:11:02 -0400 | [diff] [blame] | 1661 | <<dangling-objects>> for the details. |
J. Bruce Fields | 559e4d7 | 2007-01-29 01:31:35 -0500 | [diff] [blame] | 1662 | |
| 1663 | ------------------------------------------------- |
| 1664 | $ git fsck |
| 1665 | dangling commit 7281251ddd2a61e38657c827739c57015671a6b3 |
| 1666 | dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a63 |
| 1667 | dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b5 |
| 1668 | ... |
| 1669 | ------------------------------------------------- |
| 1670 | |
Mike Coleman | aacd404 | 2007-02-02 00:25:30 -0600 | [diff] [blame] | 1671 | You can examine |
J. Bruce Fields | 559e4d7 | 2007-01-29 01:31:35 -0500 | [diff] [blame] | 1672 | one of those dangling commits with, for example, |
| 1673 | |
| 1674 | ------------------------------------------------ |
| 1675 | $ gitk 7281251ddd --not --all |
| 1676 | ------------------------------------------------ |
| 1677 | |
| 1678 | which does what it sounds like: it says that you want to see the commit |
| 1679 | history that is described by the dangling commit(s), but not the |
| 1680 | history that is described by all your existing branches and tags. Thus |
| 1681 | you get exactly the history reachable from that commit that is lost. |
| 1682 | (And notice that it might not be just one commit: we only report the |
| 1683 | "tip of the line" as being dangling, but there might be a whole deep |
Michael Coleman | 79c96c5 | 2007-02-27 22:13:09 -0600 | [diff] [blame] | 1684 | and complex commit history that was dropped.) |
J. Bruce Fields | 559e4d7 | 2007-01-29 01:31:35 -0500 | [diff] [blame] | 1685 | |
| 1686 | If you decide you want the history back, you can always create a new |
| 1687 | reference pointing to it, for example, a new branch: |
| 1688 | |
| 1689 | ------------------------------------------------ |
Junio C Hamano | a6080a0 | 2007-06-07 00:04:01 -0700 | [diff] [blame] | 1690 | $ git branch recovered-branch 7281251ddd |
J. Bruce Fields | 559e4d7 | 2007-01-29 01:31:35 -0500 | [diff] [blame] | 1691 | ------------------------------------------------ |
| 1692 | |
J. Bruce Fields | 5972304 | 2007-04-30 11:11:02 -0400 | [diff] [blame] | 1693 | Other types of dangling objects (blobs and trees) are also possible, and |
| 1694 | dangling objects can arise in other situations. |
| 1695 | |
J. Bruce Fields | 11e016a | 2007-01-26 00:17:12 -0500 | [diff] [blame] | 1696 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 1697 | [[sharing-development]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 1698 | == Sharing development with others |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1699 | |
Junio C Hamano | aa971cb | 2008-12-07 18:38:46 -0800 | [diff] [blame] | 1700 | [[getting-updates-With-git-pull]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 1701 | === Getting updates with git pull |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1702 | |
Matthieu Moy | e63ec00 | 2009-11-22 23:26:18 +0100 | [diff] [blame] | 1703 | After you clone a repository and commit a few changes of your own, you |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1704 | may wish to check the original repository for updates and merge them |
| 1705 | into your own work. |
| 1706 | |
Junio C Hamano | aa971cb | 2008-12-07 18:38:46 -0800 | [diff] [blame] | 1707 | We have already seen <<Updating-a-repository-With-git-fetch,how to |
Matthieu Moy | 0e615b2 | 2010-11-02 16:31:20 +0100 | [diff] [blame] | 1708 | keep remote-tracking branches up to date>> with linkgit:git-fetch[1], |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1709 | and how to merge two branches. So you can merge in changes from the |
| 1710 | original repository's master branch with: |
| 1711 | |
| 1712 | ------------------------------------------------- |
| 1713 | $ git fetch |
| 1714 | $ git merge origin/master |
| 1715 | ------------------------------------------------- |
| 1716 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 1717 | However, the linkgit:git-pull[1] command provides a way to do this in |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1718 | one step: |
| 1719 | |
| 1720 | ------------------------------------------------- |
| 1721 | $ git pull origin master |
| 1722 | ------------------------------------------------- |
| 1723 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 1724 | In fact, if you have `master` checked out, then this branch has been |
| 1725 | configured by `git clone` to get changes from the HEAD branch of the |
Matthieu Moy | 66a062a | 2010-11-02 22:06:20 +0100 | [diff] [blame] | 1726 | origin repository. So often you can |
J. Bruce Fields | 0eb4f7c | 2007-08-05 17:18:52 -0400 | [diff] [blame] | 1727 | accomplish the above with just a simple |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1728 | |
| 1729 | ------------------------------------------------- |
| 1730 | $ git pull |
| 1731 | ------------------------------------------------- |
| 1732 | |
Matthieu Moy | 66a062a | 2010-11-02 22:06:20 +0100 | [diff] [blame] | 1733 | This command will fetch changes from the remote branches to your |
| 1734 | remote-tracking branches `origin/*`, and merge the default branch into |
| 1735 | the current branch. |
| 1736 | |
Matthieu Moy | 29b9a66 | 2010-11-02 16:31:24 +0100 | [diff] [blame] | 1737 | More generally, a branch that is created from a remote-tracking branch |
| 1738 | will pull |
J. Bruce Fields | 0eb4f7c | 2007-08-05 17:18:52 -0400 | [diff] [blame] | 1739 | by default from that branch. See the descriptions of the |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 1740 | `branch.<name>.remote` and `branch.<name>.merge` options in |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 1741 | linkgit:git-config[1], and the discussion of the `--track` option in |
| 1742 | linkgit:git-checkout[1], to learn how to control these defaults. |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1743 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 1744 | In addition to saving you keystrokes, `git pull` also helps you by |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1745 | producing a default commit message documenting the branch and |
| 1746 | repository that you pulled from. |
| 1747 | |
| 1748 | (But note that no such commit will be created in the case of a |
Felipe Contreras | a75d7b5 | 2009-10-24 11:31:32 +0300 | [diff] [blame] | 1749 | <<fast-forwards,fast-forward>>; instead, your branch will just be |
Michael Coleman | 79c96c5 | 2007-02-27 22:13:09 -0600 | [diff] [blame] | 1750 | updated to point to the latest commit from the upstream branch.) |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1751 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 1752 | The `git pull` command can also be given `.` as the "remote" repository, |
J. Bruce Fields | 1191ee1 | 2007-01-29 01:33:55 -0500 | [diff] [blame] | 1753 | in which case it just merges in a branch from the current repository; so |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1754 | the commands |
| 1755 | |
| 1756 | ------------------------------------------------- |
| 1757 | $ git pull . branch |
| 1758 | $ git merge branch |
| 1759 | ------------------------------------------------- |
| 1760 | |
Thomas Ackermann | a7bdee1 | 2013-08-27 19:58:18 +0200 | [diff] [blame] | 1761 | are roughly equivalent. |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1762 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 1763 | [[submitting-patches]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 1764 | === Submitting patches to a project |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1765 | |
| 1766 | If you just have a few changes, the simplest way to submit them may |
| 1767 | just be to send them as patches in email: |
| 1768 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 1769 | First, use linkgit:git-format-patch[1]; for example: |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1770 | |
| 1771 | ------------------------------------------------- |
Junio C Hamano | eb6ae7f | 2007-01-10 18:11:53 -0800 | [diff] [blame] | 1772 | $ git format-patch origin |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1773 | ------------------------------------------------- |
| 1774 | |
| 1775 | will produce a numbered series of files in the current directory, one |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 1776 | for each patch in the current branch but not in `origin/HEAD`. |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1777 | |
Philip Oakley | d84cef1 | 2012-10-21 22:34:08 +0100 | [diff] [blame] | 1778 | `git format-patch` can include an initial "cover letter". You can insert |
| 1779 | commentary on individual patches after the three dash line which |
| 1780 | `format-patch` places after the commit message but before the patch |
| 1781 | itself. If you use `git notes` to track your cover letter material, |
| 1782 | `git format-patch --notes` will include the commit's notes in a similar |
| 1783 | manner. |
| 1784 | |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1785 | You can then import these into your mail client and send them by |
| 1786 | hand. However, if you have a lot to send at once, you may prefer to |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 1787 | use the linkgit:git-send-email[1] script to automate the process. |
Jeremiah Mahler | 3c735e0 | 2014-05-27 19:23:32 -0700 | [diff] [blame] | 1788 | Consult the mailing list for your project first to determine |
| 1789 | their requirements for submitting patches. |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1790 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 1791 | [[importing-patches]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 1792 | === Importing patches to a project |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1793 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 1794 | Git also provides a tool called linkgit:git-am[1] (am stands for |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1795 | "apply mailbox"), for importing such an emailed series of patches. |
| 1796 | Just save all of the patch-containing messages, in order, into a |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 1797 | single mailbox file, say `patches.mbox`, then run |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1798 | |
| 1799 | ------------------------------------------------- |
Junio C Hamano | eb6ae7f | 2007-01-10 18:11:53 -0800 | [diff] [blame] | 1800 | $ git am -3 patches.mbox |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1801 | ------------------------------------------------- |
| 1802 | |
| 1803 | Git will apply each patch in order; if any conflicts are found, it |
| 1804 | will stop, and you can fix the conflicts as described in |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 1805 | "<<resolving-a-merge,Resolving a merge>>". (The `-3` option tells |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1806 | Git to perform a merge; if you would prefer it just to abort and |
J. Bruce Fields | 01997b4 | 2007-01-10 23:23:37 -0500 | [diff] [blame] | 1807 | leave your tree and index untouched, you may omit that option.) |
| 1808 | |
| 1809 | Once the index is updated with the results of the conflict |
| 1810 | resolution, instead of creating a new commit, just run |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1811 | |
| 1812 | ------------------------------------------------- |
Kevin Bracey | 8ceb6fb | 2013-06-26 23:06:41 +0300 | [diff] [blame] | 1813 | $ git am --continue |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1814 | ------------------------------------------------- |
| 1815 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1816 | and Git will create the commit for you and continue applying the |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1817 | remaining patches from the mailbox. |
| 1818 | |
| 1819 | The final result will be a series of commits, one for each patch in |
| 1820 | the original mailbox, with authorship and commit log message each |
| 1821 | taken from the message containing each patch. |
| 1822 | |
J. Bruce Fields | eda6944 | 2007-05-15 00:00:29 -0400 | [diff] [blame] | 1823 | [[public-repositories]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 1824 | === Public Git repositories |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1825 | |
David Kastrup | 6e30fb0 | 2007-08-08 17:34:28 +0200 | [diff] [blame] | 1826 | Another way to submit changes to a project is to tell the maintainer |
| 1827 | of that project to pull the changes from your repository using |
Junio C Hamano | aa971cb | 2008-12-07 18:38:46 -0800 | [diff] [blame] | 1828 | linkgit:git-pull[1]. In the section "<<getting-updates-With-git-pull, |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 1829 | Getting updates with `git pull`>>" we described this as a way to get |
David Kastrup | 6e30fb0 | 2007-08-08 17:34:28 +0200 | [diff] [blame] | 1830 | updates from the "main" repository, but it works just as well in the |
| 1831 | other direction. |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1832 | |
J. Bruce Fields | eda6944 | 2007-05-15 00:00:29 -0400 | [diff] [blame] | 1833 | If you and the maintainer both have accounts on the same machine, then |
| 1834 | you can just pull changes from each other's repositories directly; |
J. Bruce Fields | 11d5153 | 2007-06-18 16:38:22 -0400 | [diff] [blame] | 1835 | commands that accept repository URLs as arguments will also accept a |
J. Bruce Fields | eda6944 | 2007-05-15 00:00:29 -0400 | [diff] [blame] | 1836 | local directory name: |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1837 | |
| 1838 | ------------------------------------------------- |
| 1839 | $ git clone /path/to/repository |
| 1840 | $ git pull /path/to/other/repository |
| 1841 | ------------------------------------------------- |
| 1842 | |
Ralf Wildenhues | c901615 | 2007-10-09 23:03:55 +0200 | [diff] [blame] | 1843 | or an ssh URL: |
J. Bruce Fields | 11d5153 | 2007-06-18 16:38:22 -0400 | [diff] [blame] | 1844 | |
| 1845 | ------------------------------------------------- |
| 1846 | $ git clone ssh://yourhost/~you/repository |
| 1847 | ------------------------------------------------- |
| 1848 | |
| 1849 | For projects with few developers, or for synchronizing a few private |
| 1850 | repositories, this may be all you need. |
| 1851 | |
J. Bruce Fields | eda6944 | 2007-05-15 00:00:29 -0400 | [diff] [blame] | 1852 | However, the more common way to do this is to maintain a separate public |
| 1853 | repository (usually on a different host) for others to pull changes |
| 1854 | from. This is usually more convenient, and allows you to cleanly |
| 1855 | separate private work in progress from publicly visible work. |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1856 | |
| 1857 | You will continue to do your day-to-day work in your personal |
| 1858 | repository, but periodically "push" changes from your personal |
| 1859 | repository into your public repository, allowing other developers to |
| 1860 | pull from that repository. So the flow of changes, in a situation |
| 1861 | where there is one other developer with a public repository, looks |
| 1862 | like this: |
| 1863 | |
Martin Ågren | c4d2f61 | 2019-09-22 13:57:59 +0200 | [diff] [blame] | 1864 | .... |
| 1865 | you push |
| 1866 | your personal repo ------------------> your public repo |
| 1867 | ^ | |
| 1868 | | | |
| 1869 | | you pull | they pull |
| 1870 | | | |
| 1871 | | | |
| 1872 | | they push V |
| 1873 | their public repo <------------------- their repo |
| 1874 | .... |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1875 | |
J. Bruce Fields | 11d5153 | 2007-06-18 16:38:22 -0400 | [diff] [blame] | 1876 | We explain how to do this in the following sections. |
| 1877 | |
J. Bruce Fields | eda6944 | 2007-05-15 00:00:29 -0400 | [diff] [blame] | 1878 | [[setting-up-a-public-repository]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 1879 | ==== Setting up a public repository |
J. Bruce Fields | eda6944 | 2007-05-15 00:00:29 -0400 | [diff] [blame] | 1880 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 1881 | Assume your personal repository is in the directory `~/proj`. We |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 1882 | first create a new clone of the repository and tell `git daemon` that it |
J. Bruce Fields | eda6944 | 2007-05-15 00:00:29 -0400 | [diff] [blame] | 1883 | is meant to be public: |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1884 | |
| 1885 | ------------------------------------------------- |
J. Bruce Fields | 52c8003 | 2007-05-07 23:34:26 -0400 | [diff] [blame] | 1886 | $ git clone --bare ~/proj proj.git |
J. Bruce Fields | eda6944 | 2007-05-15 00:00:29 -0400 | [diff] [blame] | 1887 | $ touch proj.git/git-daemon-export-ok |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1888 | ------------------------------------------------- |
| 1889 | |
J. Bruce Fields | 52c8003 | 2007-05-07 23:34:26 -0400 | [diff] [blame] | 1890 | The resulting directory proj.git contains a "bare" git repository--it is |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 1891 | just the contents of the `.git` directory, without any files checked out |
J. Bruce Fields | eda6944 | 2007-05-15 00:00:29 -0400 | [diff] [blame] | 1892 | around it. |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1893 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 1894 | Next, copy `proj.git` to the server where you plan to host the |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1895 | public repository. You can use scp, rsync, or whatever is most |
| 1896 | convenient. |
| 1897 | |
J. Bruce Fields | eda6944 | 2007-05-15 00:00:29 -0400 | [diff] [blame] | 1898 | [[exporting-via-git]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 1899 | ==== Exporting a Git repository via the Git protocol |
J. Bruce Fields | eda6944 | 2007-05-15 00:00:29 -0400 | [diff] [blame] | 1900 | |
| 1901 | This is the preferred method. |
| 1902 | |
| 1903 | If someone else administers the server, they should tell you what |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 1904 | directory to put the repository in, and what `git://` URL it will |
| 1905 | appear at. You can then skip to the section |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1906 | "<<pushing-changes-to-a-public-repository,Pushing changes to a public |
| 1907 | repository>>", below. |
| 1908 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 1909 | Otherwise, all you need to do is start linkgit:git-daemon[1]; it will |
J. Bruce Fields | eda6944 | 2007-05-15 00:00:29 -0400 | [diff] [blame] | 1910 | listen on port 9418. By default, it will allow access to any directory |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1911 | that looks like a Git directory and contains the magic file |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 1912 | git-daemon-export-ok. Passing some directory paths as `git daemon` |
J. Bruce Fields | eda6944 | 2007-05-15 00:00:29 -0400 | [diff] [blame] | 1913 | arguments will further restrict the exports to those paths. |
| 1914 | |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 1915 | You can also run `git daemon` as an inetd service; see the |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 1916 | linkgit:git-daemon[1] man page for details. (See especially the |
J. Bruce Fields | eda6944 | 2007-05-15 00:00:29 -0400 | [diff] [blame] | 1917 | examples section.) |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1918 | |
| 1919 | [[exporting-via-http]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 1920 | ==== Exporting a git repository via HTTP |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1921 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1922 | The Git protocol gives better performance and reliability, but on a |
W. Trevor King | de3f2c7 | 2013-02-10 10:10:37 -0500 | [diff] [blame] | 1923 | host with a web server set up, HTTP exports may be simpler to set up. |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1924 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1925 | All you need to do is place the newly created bare Git repository in |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1926 | a directory that is exported by the web server, and make some |
| 1927 | adjustments to give web clients some extra information they need: |
| 1928 | |
| 1929 | ------------------------------------------------- |
| 1930 | $ mv proj.git /home/you/public_html/proj.git |
| 1931 | $ cd proj.git |
J. Bruce Fields | c64415e | 2007-05-07 00:56:45 -0400 | [diff] [blame] | 1932 | $ git --bare update-server-info |
Petr Baudis | 7dce991 | 2008-08-12 00:34:46 +0200 | [diff] [blame] | 1933 | $ mv hooks/post-update.sample hooks/post-update |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1934 | ------------------------------------------------- |
| 1935 | |
| 1936 | (For an explanation of the last two lines, see |
Jonathan Nieder | 6998e4d | 2008-06-30 17:01:21 -0500 | [diff] [blame] | 1937 | linkgit:git-update-server-info[1] and linkgit:githooks[5].) |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1938 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 1939 | Advertise the URL of `proj.git`. Anybody else should then be able to |
Ralf Wildenhues | c901615 | 2007-10-09 23:03:55 +0200 | [diff] [blame] | 1940 | clone or pull from that URL, for example with a command line like: |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1941 | |
| 1942 | ------------------------------------------------- |
| 1943 | $ git clone http://yourserver.com/~you/proj.git |
| 1944 | ------------------------------------------------- |
| 1945 | |
| 1946 | (See also |
Sebastian Schuberth | d5ff3b4 | 2013-09-06 22:03:22 +0200 | [diff] [blame] | 1947 | link:howto/setup-git-server-over-http.html[setup-git-server-over-http] |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1948 | for a slightly more sophisticated setup using WebDAV which also |
W. Trevor King | de3f2c7 | 2013-02-10 10:10:37 -0500 | [diff] [blame] | 1949 | allows pushing over HTTP.) |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1950 | |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1951 | [[pushing-changes-to-a-public-repository]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 1952 | ==== Pushing changes to a public repository |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1953 | |
J. Bruce Fields | eda6944 | 2007-05-15 00:00:29 -0400 | [diff] [blame] | 1954 | Note that the two techniques outlined above (exporting via |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1955 | <<exporting-via-http,http>> or <<exporting-via-git,git>>) allow other |
| 1956 | maintainers to fetch your latest changes, but they do not allow write |
| 1957 | access, which you will need to update the public repository with the |
| 1958 | latest changes created in your private repository. |
| 1959 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 1960 | The simplest way to do this is using linkgit:git-push[1] and ssh; to |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 1961 | update the remote branch named `master` with the latest state of your |
| 1962 | branch named `master`, run |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1963 | |
| 1964 | ------------------------------------------------- |
| 1965 | $ git push ssh://yourserver.com/~you/proj.git master:master |
| 1966 | ------------------------------------------------- |
| 1967 | |
| 1968 | or just |
| 1969 | |
| 1970 | ------------------------------------------------- |
| 1971 | $ git push ssh://yourserver.com/~you/proj.git master |
| 1972 | ------------------------------------------------- |
| 1973 | |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 1974 | As with `git fetch`, `git push` will complain if this does not result in a |
Felipe Contreras | a75d7b5 | 2009-10-24 11:31:32 +0300 | [diff] [blame] | 1975 | <<fast-forwards,fast-forward>>; see the following section for details on |
J. Bruce Fields | 81eb417 | 2007-11-25 17:54:19 -0500 | [diff] [blame] | 1976 | handling this case. |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1977 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 1978 | Note that the target of a `push` is normally a |
J. Bruce Fields | 11d5153 | 2007-06-18 16:38:22 -0400 | [diff] [blame] | 1979 | <<def_bare_repository,bare>> repository. You can also push to a |
W. Trevor King | d9be248 | 2013-02-08 12:04:20 -0500 | [diff] [blame] | 1980 | repository that has a checked-out working tree, but a push to update the |
| 1981 | currently checked-out branch is denied by default to prevent confusion. |
Junio C Hamano | 50995ed | 2013-02-18 12:43:00 -0800 | [diff] [blame] | 1982 | See the description of the receive.denyCurrentBranch option |
W. Trevor King | d9be248 | 2013-02-08 12:04:20 -0500 | [diff] [blame] | 1983 | in linkgit:git-config[1] for details. |
J. Bruce Fields | 11d5153 | 2007-06-18 16:38:22 -0400 | [diff] [blame] | 1984 | |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 1985 | As with `git fetch`, you may also set up configuration options to |
W. Trevor King | e9b4908 | 2013-02-17 19:15:53 -0500 | [diff] [blame] | 1986 | save typing; so, for example: |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1987 | |
| 1988 | ------------------------------------------------- |
W. Trevor King | e9b4908 | 2013-02-17 19:15:53 -0500 | [diff] [blame] | 1989 | $ git remote add public-repo ssh://yourserver.com/~you/proj.git |
| 1990 | ------------------------------------------------- |
| 1991 | |
| 1992 | adds the following to `.git/config`: |
| 1993 | |
| 1994 | ------------------------------------------------- |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1995 | [remote "public-repo"] |
W. Trevor King | e9b4908 | 2013-02-17 19:15:53 -0500 | [diff] [blame] | 1996 | url = yourserver.com:proj.git |
| 1997 | fetch = +refs/heads/*:refs/remotes/example/* |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 1998 | ------------------------------------------------- |
| 1999 | |
W. Trevor King | e9b4908 | 2013-02-17 19:15:53 -0500 | [diff] [blame] | 2000 | which lets you do the same push with just |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 2001 | |
| 2002 | ------------------------------------------------- |
| 2003 | $ git push public-repo master |
| 2004 | ------------------------------------------------- |
| 2005 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 2006 | See the explanations of the `remote.<name>.url`, |
| 2007 | `branch.<name>.remote`, and `remote.<name>.push` options in |
| 2008 | linkgit:git-config[1] for details. |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 2009 | |
J. Bruce Fields | 81eb417 | 2007-11-25 17:54:19 -0500 | [diff] [blame] | 2010 | [[forcing-push]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 2011 | ==== What to do when a push fails |
J. Bruce Fields | 81eb417 | 2007-11-25 17:54:19 -0500 | [diff] [blame] | 2012 | |
Felipe Contreras | a75d7b5 | 2009-10-24 11:31:32 +0300 | [diff] [blame] | 2013 | If a push would not result in a <<fast-forwards,fast-forward>> of the |
J. Bruce Fields | 81eb417 | 2007-11-25 17:54:19 -0500 | [diff] [blame] | 2014 | remote branch, then it will fail with an error like: |
| 2015 | |
| 2016 | ------------------------------------------------- |
Martin Ågren | 3c82eec | 2017-08-23 19:49:34 +0200 | [diff] [blame] | 2017 | ! [rejected] master -> master (non-fast-forward) |
| 2018 | error: failed to push some refs to '...' |
| 2019 | hint: Updates were rejected because the tip of your current branch is behind |
| 2020 | hint: its remote counterpart. Integrate the remote changes (e.g. |
| 2021 | hint: 'git pull ...') before pushing again. |
| 2022 | hint: See the 'Note about fast-forwards' in 'git push --help' for details. |
J. Bruce Fields | 81eb417 | 2007-11-25 17:54:19 -0500 | [diff] [blame] | 2023 | ------------------------------------------------- |
| 2024 | |
| 2025 | This can happen, for example, if you: |
| 2026 | |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 2027 | - use `git reset --hard` to remove already-published commits, or |
| 2028 | - use `git commit --amend` to replace already-published commits |
J. Bruce Fields | 7cb192e | 2007-11-25 19:01:57 -0500 | [diff] [blame] | 2029 | (as in <<fixing-a-mistake-by-rewriting-history>>), or |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 2030 | - use `git rebase` to rebase any already-published commits (as |
J. Bruce Fields | 81eb417 | 2007-11-25 17:54:19 -0500 | [diff] [blame] | 2031 | in <<using-git-rebase>>). |
| 2032 | |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 2033 | You may force `git push` to perform the update anyway by preceding the |
J. Bruce Fields | 81eb417 | 2007-11-25 17:54:19 -0500 | [diff] [blame] | 2034 | branch name with a plus sign: |
| 2035 | |
| 2036 | ------------------------------------------------- |
| 2037 | $ git push ssh://yourserver.com/~you/proj.git +master |
| 2038 | ------------------------------------------------- |
| 2039 | |
W. Trevor King | d1471e0 | 2013-02-17 19:15:55 -0500 | [diff] [blame] | 2040 | Note the addition of the `+` sign. Alternatively, you can use the |
| 2041 | `-f` flag to force the remote update, as in: |
| 2042 | |
| 2043 | ------------------------------------------------- |
| 2044 | $ git push -f ssh://yourserver.com/~you/proj.git master |
| 2045 | ------------------------------------------------- |
| 2046 | |
J. Bruce Fields | 81eb417 | 2007-11-25 17:54:19 -0500 | [diff] [blame] | 2047 | Normally whenever a branch head in a public repository is modified, it |
Shawn Bohrer | 9e5d87d | 2007-12-12 22:36:21 -0600 | [diff] [blame] | 2048 | is modified to point to a descendant of the commit that it pointed to |
J. Bruce Fields | 81eb417 | 2007-11-25 17:54:19 -0500 | [diff] [blame] | 2049 | before. By forcing a push in this situation, you break that convention. |
Junio C Hamano | aa971cb | 2008-12-07 18:38:46 -0800 | [diff] [blame] | 2050 | (See <<problems-With-rewriting-history>>.) |
J. Bruce Fields | 81eb417 | 2007-11-25 17:54:19 -0500 | [diff] [blame] | 2051 | |
| 2052 | Nevertheless, this is a common practice for people that need a simple |
| 2053 | way to publish a work-in-progress patch series, and it is an acceptable |
| 2054 | compromise as long as you warn other developers that this is how you |
| 2055 | intend to manage the branch. |
| 2056 | |
| 2057 | It's also possible for a push to fail in this way when other people have |
| 2058 | the right to push to the same repository. In that case, the correct |
Eric Hanchrow | 843c81d | 2008-07-08 13:00:30 -0700 | [diff] [blame] | 2059 | solution is to retry the push after first updating your work: either by a |
| 2060 | pull, or by a fetch followed by a rebase; see the |
J. Bruce Fields | 81eb417 | 2007-11-25 17:54:19 -0500 | [diff] [blame] | 2061 | <<setting-up-a-shared-repository,next section>> and |
Jonathan Nieder | 6998e4d | 2008-06-30 17:01:21 -0500 | [diff] [blame] | 2062 | linkgit:gitcvs-migration[7] for more. |
J. Bruce Fields | 81eb417 | 2007-11-25 17:54:19 -0500 | [diff] [blame] | 2063 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 2064 | [[setting-up-a-shared-repository]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 2065 | ==== Setting up a shared repository |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 2066 | |
| 2067 | Another way to collaborate is by using a model similar to that |
| 2068 | commonly used in CVS, where several developers with special rights |
| 2069 | all push to and pull from a single shared repository. See |
Jonathan Nieder | 6998e4d | 2008-06-30 17:01:21 -0500 | [diff] [blame] | 2070 | linkgit:gitcvs-migration[7] for instructions on how to |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 2071 | set this up. |
| 2072 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 2073 | However, while there is nothing wrong with Git's support for shared |
J. Bruce Fields | 8fae222 | 2007-05-15 00:30:58 -0400 | [diff] [blame] | 2074 | repositories, this mode of operation is not generally recommended, |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 2075 | simply because the mode of collaboration that Git supports--by |
J. Bruce Fields | 8fae222 | 2007-05-15 00:30:58 -0400 | [diff] [blame] | 2076 | exchanging patches and pulling from public repositories--has so many |
| 2077 | advantages over the central shared repository: |
| 2078 | |
| 2079 | - Git's ability to quickly import and merge patches allows a |
| 2080 | single maintainer to process incoming changes even at very |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 2081 | high rates. And when that becomes too much, `git pull` provides |
J. Bruce Fields | 8fae222 | 2007-05-15 00:30:58 -0400 | [diff] [blame] | 2082 | an easy way for that maintainer to delegate this job to other |
| 2083 | maintainers while still allowing optional review of incoming |
| 2084 | changes. |
| 2085 | - Since every developer's repository has the same complete copy |
| 2086 | of the project history, no repository is special, and it is |
| 2087 | trivial for another developer to take over maintenance of a |
| 2088 | project, either by mutual agreement, or because a maintainer |
| 2089 | becomes unresponsive or difficult to work with. |
| 2090 | - The lack of a central group of "committers" means there is |
| 2091 | less need for formal decisions about who is "in" and who is |
| 2092 | "out". |
| 2093 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 2094 | [[setting-up-gitweb]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 2095 | ==== Allowing web browsing of a repository |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 2096 | |
J. Bruce Fields | a8cd140 | 2007-01-30 12:43:36 -0500 | [diff] [blame] | 2097 | The gitweb cgi script provides users an easy way to browse your |
Stephen P. Smith | 99487cf | 2015-12-30 16:25:20 -0700 | [diff] [blame] | 2098 | project's revisions, file contents and logs without having to install |
| 2099 | Git. Features like RSS/Atom feeds and blame/annotation details may |
| 2100 | optionally be enabled. |
| 2101 | |
| 2102 | The linkgit:git-instaweb[1] command provides a simple way to start |
| 2103 | browsing the repository using gitweb. The default server when using |
| 2104 | instaweb is lighttpd. |
| 2105 | |
| 2106 | See the file gitweb/INSTALL in the Git source tree and |
Thomas Ackermann | d285ab0 | 2016-03-03 19:43:51 +0100 | [diff] [blame] | 2107 | linkgit:gitweb[1] for instructions on details setting up a permanent |
Stephen P. Smith | 99487cf | 2015-12-30 16:25:20 -0700 | [diff] [blame] | 2108 | installation with a CGI or Perl capable server. |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 2109 | |
Stephen P. Smith | 9cfde9e | 2015-12-29 17:03:50 -0700 | [diff] [blame] | 2110 | [[how-to-get-a-git-repository-with-minimal-history]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 2111 | === How to get a Git repository with minimal history |
Stephen P. Smith | 9cfde9e | 2015-12-29 17:03:50 -0700 | [diff] [blame] | 2112 | |
| 2113 | A <<def_shallow_clone,shallow clone>>, with its truncated |
| 2114 | history, is useful when one is interested only in recent history |
| 2115 | of a project and getting full history from the upstream is |
| 2116 | expensive. |
| 2117 | |
| 2118 | A <<def_shallow_clone,shallow clone>> is created by specifying |
| 2119 | the linkgit:git-clone[1] `--depth` switch. The depth can later be |
| 2120 | changed with the linkgit:git-fetch[1] `--depth` switch, or full |
| 2121 | history restored with `--unshallow`. |
| 2122 | |
| 2123 | Merging inside a <<def_shallow_clone,shallow clone>> will work as long |
| 2124 | as a merge base is in the recent history. |
| 2125 | Otherwise, it will be like merging unrelated histories and may |
| 2126 | have to result in huge conflicts. This limitation may make such |
| 2127 | a repository unsuitable to be used in merge based workflows. |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 2128 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 2129 | [[sharing-development-examples]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 2130 | === Examples |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 2131 | |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2132 | [[maintaining-topic-branches]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 2133 | ==== Maintaining topic branches for a Linux subsystem maintainer |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2134 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 2135 | This describes how Tony Luck uses Git in his role as maintainer of the |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2136 | IA64 architecture for the Linux kernel. |
| 2137 | |
| 2138 | He uses two public branches: |
| 2139 | |
| 2140 | - A "test" tree into which patches are initially placed so that they |
| 2141 | can get some exposure when integrated with other ongoing development. |
| 2142 | This tree is available to Andrew for pulling into -mm whenever he |
| 2143 | wants. |
| 2144 | |
| 2145 | - A "release" tree into which tested patches are moved for final sanity |
| 2146 | checking, and as a vehicle to send them upstream to Linus (by sending |
| 2147 | him a "please pull" request.) |
| 2148 | |
| 2149 | He also uses a set of temporary branches ("topic branches"), each |
| 2150 | containing a logical grouping of patches. |
| 2151 | |
| 2152 | To set this up, first create your work tree by cloning Linus's public |
| 2153 | tree: |
| 2154 | |
| 2155 | ------------------------------------------------- |
W. Trevor King | 283efb0 | 2013-06-22 10:46:27 -0400 | [diff] [blame] | 2156 | $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git work |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2157 | $ cd work |
| 2158 | ------------------------------------------------- |
| 2159 | |
Matthieu Moy | 29b9a66 | 2010-11-02 16:31:24 +0100 | [diff] [blame] | 2160 | Linus's tree will be stored in the remote-tracking branch named origin/master, |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 2161 | and can be updated using linkgit:git-fetch[1]; you can track other |
| 2162 | public trees using linkgit:git-remote[1] to set up a "remote" and |
Martin Ågren | 7560f54 | 2017-08-23 19:49:35 +0200 | [diff] [blame] | 2163 | linkgit:git-fetch[1] to keep them up to date; see |
David Kastrup | 6e30fb0 | 2007-08-08 17:34:28 +0200 | [diff] [blame] | 2164 | <<repositories-and-branches>>. |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2165 | |
| 2166 | Now create the branches in which you are going to work; these start out |
| 2167 | at the current tip of origin/master branch, and should be set up (using |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 2168 | the `--track` option to linkgit:git-branch[1]) to merge changes in from |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2169 | Linus by default. |
| 2170 | |
| 2171 | ------------------------------------------------- |
| 2172 | $ git branch --track test origin/master |
| 2173 | $ git branch --track release origin/master |
| 2174 | ------------------------------------------------- |
| 2175 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 2176 | These can be easily kept up to date using linkgit:git-pull[1]. |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2177 | |
| 2178 | ------------------------------------------------- |
Nguyễn Thái Ngọc Duy | 328c6cb | 2019-03-29 17:39:19 +0700 | [diff] [blame] | 2179 | $ git switch test && git pull |
| 2180 | $ git switch release && git pull |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2181 | ------------------------------------------------- |
| 2182 | |
| 2183 | Important note! If you have any local changes in these branches, then |
| 2184 | this merge will create a commit object in the history (with no local |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 2185 | changes Git will simply do a "fast-forward" merge). Many people dislike |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2186 | the "noise" that this creates in the Linux history, so you should avoid |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 2187 | doing this capriciously in the `release` branch, as these noisy commits |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2188 | will become part of the permanent history when you ask Linus to pull |
| 2189 | from the release branch. |
| 2190 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 2191 | A few configuration variables (see linkgit:git-config[1]) can |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2192 | make it easy to push both branches to your public tree. (See |
| 2193 | <<setting-up-a-public-repository>>.) |
| 2194 | |
| 2195 | ------------------------------------------------- |
| 2196 | $ cat >> .git/config <<EOF |
| 2197 | [remote "mytree"] |
W. Trevor King | 283efb0 | 2013-06-22 10:46:27 -0400 | [diff] [blame] | 2198 | url = master.kernel.org:/pub/scm/linux/kernel/git/aegl/linux.git |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2199 | push = release |
| 2200 | push = test |
| 2201 | EOF |
| 2202 | ------------------------------------------------- |
| 2203 | |
| 2204 | Then you can push both the test and release trees using |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 2205 | linkgit:git-push[1]: |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2206 | |
| 2207 | ------------------------------------------------- |
| 2208 | $ git push mytree |
| 2209 | ------------------------------------------------- |
| 2210 | |
| 2211 | or push just one of the test and release branches using: |
| 2212 | |
| 2213 | ------------------------------------------------- |
| 2214 | $ git push mytree test |
| 2215 | ------------------------------------------------- |
| 2216 | |
| 2217 | or |
| 2218 | |
| 2219 | ------------------------------------------------- |
| 2220 | $ git push mytree release |
| 2221 | ------------------------------------------------- |
| 2222 | |
| 2223 | Now to apply some patches from the community. Think of a short |
| 2224 | snappy name for a branch to hold this patch (or related group of |
Luck, Tony | 352953a | 2010-10-01 11:57:52 -0700 | [diff] [blame] | 2225 | patches), and create a new branch from a recent stable tag of |
| 2226 | Linus's branch. Picking a stable base for your branch will: |
| 2227 | 1) help you: by avoiding inclusion of unrelated and perhaps lightly |
| 2228 | tested changes |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 2229 | 2) help future bug hunters that use `git bisect` to find problems |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2230 | |
| 2231 | ------------------------------------------------- |
Nguyễn Thái Ngọc Duy | 328c6cb | 2019-03-29 17:39:19 +0700 | [diff] [blame] | 2232 | $ git switch -c speed-up-spinlocks v2.6.35 |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2233 | ------------------------------------------------- |
| 2234 | |
| 2235 | Now you apply the patch(es), run some tests, and commit the change(s). If |
| 2236 | the patch is a multi-part series, then you should apply each as a separate |
| 2237 | commit to this branch. |
| 2238 | |
| 2239 | ------------------------------------------------- |
| 2240 | $ ... patch ... test ... commit [ ... patch ... test ... commit ]* |
| 2241 | ------------------------------------------------- |
| 2242 | |
Thomas Ackermann | a7bdee1 | 2013-08-27 19:58:18 +0200 | [diff] [blame] | 2243 | When you are happy with the state of this change, you can merge it into the |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2244 | "test" branch in preparation to make it public: |
| 2245 | |
| 2246 | ------------------------------------------------- |
Nguyễn Thái Ngọc Duy | 328c6cb | 2019-03-29 17:39:19 +0700 | [diff] [blame] | 2247 | $ git switch test && git merge speed-up-spinlocks |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2248 | ------------------------------------------------- |
| 2249 | |
| 2250 | It is unlikely that you would have any conflicts here ... but you might if you |
| 2251 | spent a while on this step and had also pulled new versions from upstream. |
| 2252 | |
Jeremiah Mahler | 3c735e0 | 2014-05-27 19:23:32 -0700 | [diff] [blame] | 2253 | Sometime later when enough time has passed and testing done, you can pull the |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 2254 | same branch into the `release` tree ready to go upstream. This is where you |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2255 | see the value of keeping each patch (or patch series) in its own branch. It |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 2256 | means that the patches can be moved into the `release` tree in any order. |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2257 | |
| 2258 | ------------------------------------------------- |
Nguyễn Thái Ngọc Duy | 328c6cb | 2019-03-29 17:39:19 +0700 | [diff] [blame] | 2259 | $ git switch release && git merge speed-up-spinlocks |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2260 | ------------------------------------------------- |
| 2261 | |
| 2262 | After a while, you will have a number of branches, and despite the |
| 2263 | well chosen names you picked for each of them, you may forget what |
| 2264 | they are for, or what status they are in. To get a reminder of what |
| 2265 | changes are in a specific branch, use: |
| 2266 | |
| 2267 | ------------------------------------------------- |
Jonathan Nieder | 467c019 | 2008-07-03 00:28:15 -0500 | [diff] [blame] | 2268 | $ git log linux..branchname | git shortlog |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2269 | ------------------------------------------------- |
| 2270 | |
Ralf Wildenhues | 06ada15 | 2007-10-09 23:00:03 +0200 | [diff] [blame] | 2271 | To see whether it has already been merged into the test or release branches, |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2272 | use: |
| 2273 | |
| 2274 | ------------------------------------------------- |
| 2275 | $ git log test..branchname |
| 2276 | ------------------------------------------------- |
| 2277 | |
| 2278 | or |
| 2279 | |
| 2280 | ------------------------------------------------- |
| 2281 | $ git log release..branchname |
| 2282 | ------------------------------------------------- |
| 2283 | |
Ralf Wildenhues | 06ada15 | 2007-10-09 23:00:03 +0200 | [diff] [blame] | 2284 | (If this branch has not yet been merged, you will see some log entries. |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2285 | If it has been merged, then there will be no output.) |
| 2286 | |
| 2287 | Once a patch completes the great cycle (moving from test to release, |
| 2288 | then pulled by Linus, and finally coming back into your local |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 2289 | `origin/master` branch), the branch for this change is no longer needed. |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2290 | You detect this when the output from: |
| 2291 | |
| 2292 | ------------------------------------------------- |
| 2293 | $ git log origin..branchname |
| 2294 | ------------------------------------------------- |
| 2295 | |
| 2296 | is empty. At this point the branch can be deleted: |
| 2297 | |
| 2298 | ------------------------------------------------- |
| 2299 | $ git branch -d branchname |
| 2300 | ------------------------------------------------- |
| 2301 | |
| 2302 | Some changes are so trivial that it is not necessary to create a separate |
| 2303 | branch and then merge into each of the test and release branches. For |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 2304 | these changes, just apply directly to the `release` branch, and then |
| 2305 | merge that into the `test` branch. |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2306 | |
W. Trevor King | ae6ef55 | 2013-02-19 05:05:01 -0500 | [diff] [blame] | 2307 | After pushing your work to `mytree`, you can use |
| 2308 | linkgit:git-request-pull[1] to prepare a "please pull" request message |
| 2309 | to send to Linus: |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2310 | |
| 2311 | ------------------------------------------------- |
W. Trevor King | ae6ef55 | 2013-02-19 05:05:01 -0500 | [diff] [blame] | 2312 | $ git push mytree |
| 2313 | $ git request-pull origin mytree release |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2314 | ------------------------------------------------- |
| 2315 | |
| 2316 | Here are some of the scripts that simplify all this even further. |
| 2317 | |
| 2318 | ------------------------------------------------- |
| 2319 | ==== update script ==== |
Thomas Ackermann | 48a8c26 | 2013-01-21 20:16:20 +0100 | [diff] [blame] | 2320 | # Update a branch in my Git tree. If the branch to be updated |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2321 | # is origin, then pull from kernel.org. Otherwise merge |
| 2322 | # origin/master branch into test|release branch |
| 2323 | |
| 2324 | case "$1" in |
| 2325 | test|release) |
| 2326 | git checkout $1 && git pull . origin |
| 2327 | ;; |
| 2328 | origin) |
J. Bruce Fields | fc74ecc | 2007-09-09 22:07:02 -0400 | [diff] [blame] | 2329 | before=$(git rev-parse refs/remotes/origin/master) |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2330 | git fetch origin |
J. Bruce Fields | fc74ecc | 2007-09-09 22:07:02 -0400 | [diff] [blame] | 2331 | after=$(git rev-parse refs/remotes/origin/master) |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2332 | if [ $before != $after ] |
| 2333 | then |
| 2334 | git log $before..$after | git shortlog |
| 2335 | fi |
| 2336 | ;; |
| 2337 | *) |
David Aguilar | 1a2ba8b | 2013-02-23 16:50:24 -0800 | [diff] [blame] | 2338 | echo "usage: $0 origin|test|release" 1>&2 |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2339 | exit 1 |
| 2340 | ;; |
| 2341 | esac |
| 2342 | ------------------------------------------------- |
| 2343 | |
| 2344 | ------------------------------------------------- |
| 2345 | ==== merge script ==== |
| 2346 | # Merge a branch into either the test or release branch |
| 2347 | |
| 2348 | pname=$0 |
| 2349 | |
| 2350 | usage() |
| 2351 | { |
David Aguilar | 1a2ba8b | 2013-02-23 16:50:24 -0800 | [diff] [blame] | 2352 | echo "usage: $pname branch test|release" 1>&2 |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2353 | exit 1 |
| 2354 | } |
| 2355 | |
J. Bruce Fields | fc74ecc | 2007-09-09 22:07:02 -0400 | [diff] [blame] | 2356 | git show-ref -q --verify -- refs/heads/"$1" || { |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2357 | echo "Can't see branch <$1>" 1>&2 |
| 2358 | usage |
J. Bruce Fields | fc74ecc | 2007-09-09 22:07:02 -0400 | [diff] [blame] | 2359 | } |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2360 | |
| 2361 | case "$2" in |
| 2362 | test|release) |
| 2363 | if [ $(git log $2..$1 | wc -c) -eq 0 ] |
| 2364 | then |
| 2365 | echo $1 already merged into $2 1>&2 |
| 2366 | exit 1 |
| 2367 | fi |
| 2368 | git checkout $2 && git pull . $1 |
| 2369 | ;; |
| 2370 | *) |
| 2371 | usage |
| 2372 | ;; |
| 2373 | esac |
| 2374 | ------------------------------------------------- |
| 2375 | |
| 2376 | ------------------------------------------------- |
| 2377 | ==== status script ==== |
Thomas Ackermann | 48a8c26 | 2013-01-21 20:16:20 +0100 | [diff] [blame] | 2378 | # report on status of my ia64 Git tree |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2379 | |
| 2380 | gb=$(tput setab 2) |
| 2381 | rb=$(tput setab 1) |
| 2382 | restore=$(tput setab 9) |
| 2383 | |
| 2384 | if [ `git rev-list test..release | wc -c` -gt 0 ] |
| 2385 | then |
| 2386 | echo $rb Warning: commits in release that are not in test $restore |
| 2387 | git log test..release |
| 2388 | fi |
| 2389 | |
J. Bruce Fields | fc74ecc | 2007-09-09 22:07:02 -0400 | [diff] [blame] | 2390 | for branch in `git show-ref --heads | sed 's|^.*/||'` |
J. Bruce Fields | 9e2163e | 2007-05-13 01:48:47 -0400 | [diff] [blame] | 2391 | do |
| 2392 | if [ $branch = test -o $branch = release ] |
| 2393 | then |
| 2394 | continue |
| 2395 | fi |
| 2396 | |
| 2397 | echo -n $gb ======= $branch ====== $restore " " |
| 2398 | status= |
| 2399 | for ref in test release origin/master |
| 2400 | do |
| 2401 | if [ `git rev-list $ref..$branch | wc -c` -gt 0 ] |
| 2402 | then |
| 2403 | status=$status${ref:0:1} |
| 2404 | fi |
| 2405 | done |
| 2406 | case $status in |
| 2407 | trl) |
| 2408 | echo $rb Need to pull into test $restore |
| 2409 | ;; |
| 2410 | rl) |
| 2411 | echo "In test" |
| 2412 | ;; |
| 2413 | l) |
| 2414 | echo "Waiting for linus" |
| 2415 | ;; |
| 2416 | "") |
| 2417 | echo $rb All done $restore |
| 2418 | ;; |
| 2419 | *) |
| 2420 | echo $rb "<$status>" $restore |
| 2421 | ;; |
| 2422 | esac |
| 2423 | git log origin/master..$branch | git shortlog |
| 2424 | done |
| 2425 | ------------------------------------------------- |
J. Bruce Fields | b684f83 | 2007-01-08 23:42:36 -0500 | [diff] [blame] | 2426 | |
| 2427 | |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 2428 | [[cleaning-up-history]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 2429 | == Rewriting history and maintaining patch series |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 2430 | |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2431 | Normally commits are only added to a project, never taken away or |
| 2432 | replaced. Git is designed with this assumption, and violating it will |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 2433 | cause Git's merge machinery (for example) to do the wrong thing. |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2434 | |
| 2435 | However, there is a situation in which it can be useful to violate this |
| 2436 | assumption. |
| 2437 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 2438 | [[patch-series]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 2439 | === Creating the perfect patch series |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2440 | |
| 2441 | Suppose you are a contributor to a large project, and you want to add a |
| 2442 | complicated feature, and to present it to the other developers in a way |
| 2443 | that makes it easy for them to read your changes, verify that they are |
| 2444 | correct, and understand why you made each change. |
| 2445 | |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2446 | If you present all of your changes as a single patch (or commit), they |
Michael Coleman | 79c96c5 | 2007-02-27 22:13:09 -0600 | [diff] [blame] | 2447 | may find that it is too much to digest all at once. |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2448 | |
| 2449 | If you present them with the entire history of your work, complete with |
| 2450 | mistakes, corrections, and dead ends, they may be overwhelmed. |
| 2451 | |
| 2452 | So the ideal is usually to produce a series of patches such that: |
| 2453 | |
| 2454 | 1. Each patch can be applied in order. |
| 2455 | |
| 2456 | 2. Each patch includes a single logical change, together with a |
| 2457 | message explaining the change. |
| 2458 | |
| 2459 | 3. No patch introduces a regression: after applying any initial |
| 2460 | part of the series, the resulting project still compiles and |
| 2461 | works, and has no bugs that it didn't have before. |
| 2462 | |
| 2463 | 4. The complete series produces the same end result as your own |
| 2464 | (probably much messier!) development process did. |
| 2465 | |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2466 | We will introduce some tools that can help you do this, explain how to |
| 2467 | use them, and then explain some of the problems that can arise because |
| 2468 | you are rewriting history. |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2469 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 2470 | [[using-git-rebase]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 2471 | === Keeping a patch series up to date using git rebase |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2472 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 2473 | Suppose that you create a branch `mywork` on a remote-tracking branch |
| 2474 | `origin`, and create some commits on top of it: |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2475 | |
| 2476 | ------------------------------------------------- |
Nguyễn Thái Ngọc Duy | 328c6cb | 2019-03-29 17:39:19 +0700 | [diff] [blame] | 2477 | $ git switch -c mywork origin |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2478 | $ vi file.txt |
| 2479 | $ git commit |
| 2480 | $ vi otherfile.txt |
| 2481 | $ git commit |
| 2482 | ... |
| 2483 | ------------------------------------------------- |
| 2484 | |
| 2485 | You have performed no merges into mywork, so it is just a simple linear |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 2486 | sequence of patches on top of `origin`: |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2487 | |
J. Bruce Fields | 1dc71a9 | 2007-03-10 22:38:13 -0500 | [diff] [blame] | 2488 | ................................................ |
Kirill Smelkov | fa8347b | 2010-09-28 12:20:24 +0400 | [diff] [blame] | 2489 | o--o--O <-- origin |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2490 | \ |
Kirill Smelkov | fa8347b | 2010-09-28 12:20:24 +0400 | [diff] [blame] | 2491 | a--b--c <-- mywork |
J. Bruce Fields | 1dc71a9 | 2007-03-10 22:38:13 -0500 | [diff] [blame] | 2492 | ................................................ |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2493 | |
| 2494 | Some more interesting work has been done in the upstream project, and |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 2495 | `origin` has advanced: |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2496 | |
J. Bruce Fields | 1dc71a9 | 2007-03-10 22:38:13 -0500 | [diff] [blame] | 2497 | ................................................ |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2498 | o--o--O--o--o--o <-- origin |
| 2499 | \ |
| 2500 | a--b--c <-- mywork |
J. Bruce Fields | 1dc71a9 | 2007-03-10 22:38:13 -0500 | [diff] [blame] | 2501 | ................................................ |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2502 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 2503 | At this point, you could use `pull` to merge your changes back in; |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2504 | the result would create a new merge commit, like this: |
| 2505 | |
J. Bruce Fields | 1dc71a9 | 2007-03-10 22:38:13 -0500 | [diff] [blame] | 2506 | ................................................ |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2507 | o--o--O--o--o--o <-- origin |
| 2508 | \ \ |
| 2509 | a--b--c--m <-- mywork |
J. Bruce Fields | 1dc71a9 | 2007-03-10 22:38:13 -0500 | [diff] [blame] | 2510 | ................................................ |
Junio C Hamano | a6080a0 | 2007-06-07 00:04:01 -0700 | [diff] [blame] | 2511 | |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2512 | However, if you prefer to keep the history in mywork a simple series of |
| 2513 | commits without any merges, you may instead choose to use |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 2514 | linkgit:git-rebase[1]: |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2515 | |
| 2516 | ------------------------------------------------- |
Nguyễn Thái Ngọc Duy | 328c6cb | 2019-03-29 17:39:19 +0700 | [diff] [blame] | 2517 | $ git switch mywork |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2518 | $ git rebase origin |
| 2519 | ------------------------------------------------- |
| 2520 | |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2521 | This will remove each of your commits from mywork, temporarily saving |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 2522 | them as patches (in a directory named `.git/rebase-apply`), update mywork to |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2523 | point at the latest version of origin, then apply each of the saved |
| 2524 | patches to the new mywork. The result will look like: |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2525 | |
| 2526 | |
J. Bruce Fields | 1dc71a9 | 2007-03-10 22:38:13 -0500 | [diff] [blame] | 2527 | ................................................ |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2528 | o--o--O--o--o--o <-- origin |
| 2529 | \ |
| 2530 | a'--b'--c' <-- mywork |
J. Bruce Fields | 1dc71a9 | 2007-03-10 22:38:13 -0500 | [diff] [blame] | 2531 | ................................................ |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2532 | |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2533 | In the process, it may discover conflicts. In that case it will stop |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 2534 | and allow you to fix the conflicts; after fixing conflicts, use `git add` |
Jonathan Nieder | 7a7d4ef | 2008-07-03 00:20:21 -0500 | [diff] [blame] | 2535 | to update the index with those contents, and then, instead of |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 2536 | running `git commit`, just run |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2537 | |
| 2538 | ------------------------------------------------- |
| 2539 | $ git rebase --continue |
| 2540 | ------------------------------------------------- |
| 2541 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 2542 | and Git will continue applying the rest of the patches. |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2543 | |
Ralf Wildenhues | b6cbca3 | 2007-10-09 23:03:11 +0200 | [diff] [blame] | 2544 | At any point you may use the `--abort` option to abort this process and |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2545 | return mywork to the state it had before you started the rebase: |
| 2546 | |
| 2547 | ------------------------------------------------- |
| 2548 | $ git rebase --abort |
| 2549 | ------------------------------------------------- |
| 2550 | |
W. Trevor King | 6c26bf4 | 2013-02-19 05:05:00 -0500 | [diff] [blame] | 2551 | If you need to reorder or edit a number of commits in a branch, it may |
| 2552 | be easier to use `git rebase -i`, which allows you to reorder and |
| 2553 | squash commits, as well as marking them for individual editing during |
| 2554 | the rebase. See <<interactive-rebase>> for details, and |
| 2555 | <<reordering-patch-series>> for alternatives. |
| 2556 | |
J. Bruce Fields | 7cb192e | 2007-11-25 19:01:57 -0500 | [diff] [blame] | 2557 | [[rewriting-one-commit]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 2558 | === Rewriting a single commit |
J. Bruce Fields | 365aa19 | 2007-03-03 14:30:32 -0500 | [diff] [blame] | 2559 | |
J. Bruce Fields | 7cb192e | 2007-11-25 19:01:57 -0500 | [diff] [blame] | 2560 | We saw in <<fixing-a-mistake-by-rewriting-history>> that you can replace the |
J. Bruce Fields | 365aa19 | 2007-03-03 14:30:32 -0500 | [diff] [blame] | 2561 | most recent commit using |
| 2562 | |
| 2563 | ------------------------------------------------- |
| 2564 | $ git commit --amend |
| 2565 | ------------------------------------------------- |
| 2566 | |
| 2567 | which will replace the old commit by a new commit incorporating your |
| 2568 | changes, giving you a chance to edit the old commit message first. |
W. Trevor King | 6c26bf4 | 2013-02-19 05:05:00 -0500 | [diff] [blame] | 2569 | This is useful for fixing typos in your last commit, or for adjusting |
| 2570 | the patch contents of a poorly staged commit. |
J. Bruce Fields | 365aa19 | 2007-03-03 14:30:32 -0500 | [diff] [blame] | 2571 | |
W. Trevor King | 6c26bf4 | 2013-02-19 05:05:00 -0500 | [diff] [blame] | 2572 | If you need to amend commits from deeper in your history, you can |
| 2573 | use <<interactive-rebase,interactive rebase's `edit` instruction>>. |
J. Bruce Fields | 365aa19 | 2007-03-03 14:30:32 -0500 | [diff] [blame] | 2574 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 2575 | [[reordering-patch-series]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 2576 | === Reordering or selecting from a patch series |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2577 | |
W. Trevor King | 6c26bf4 | 2013-02-19 05:05:00 -0500 | [diff] [blame] | 2578 | Sometimes you want to edit a commit deeper in your history. One |
| 2579 | approach is to use `git format-patch` to create a series of patches |
| 2580 | and then reset the state to before the patches: |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2581 | |
| 2582 | ------------------------------------------------- |
| 2583 | $ git format-patch origin |
| 2584 | $ git reset --hard origin |
| 2585 | ------------------------------------------------- |
| 2586 | |
W. Trevor King | 6c26bf4 | 2013-02-19 05:05:00 -0500 | [diff] [blame] | 2587 | Then modify, reorder, or eliminate patches as needed before applying |
| 2588 | them again with linkgit:git-am[1]: |
| 2589 | |
| 2590 | ------------------------------------------------- |
| 2591 | $ git am *.patch |
| 2592 | ------------------------------------------------- |
| 2593 | |
| 2594 | [[interactive-rebase]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 2595 | === Using interactive rebases |
W. Trevor King | 6c26bf4 | 2013-02-19 05:05:00 -0500 | [diff] [blame] | 2596 | |
| 2597 | You can also edit a patch series with an interactive rebase. This is |
| 2598 | the same as <<reordering-patch-series,reordering a patch series using |
| 2599 | `format-patch`>>, so use whichever interface you like best. |
| 2600 | |
| 2601 | Rebase your current HEAD on the last commit you want to retain as-is. |
| 2602 | For example, if you want to reorder the last 5 commits, use: |
| 2603 | |
| 2604 | ------------------------------------------------- |
| 2605 | $ git rebase -i HEAD~5 |
| 2606 | ------------------------------------------------- |
| 2607 | |
| 2608 | This will open your editor with a list of steps to be taken to perform |
| 2609 | your rebase. |
| 2610 | |
| 2611 | ------------------------------------------------- |
| 2612 | pick deadbee The oneline of this commit |
| 2613 | pick fa1afe1 The oneline of the next commit |
| 2614 | ... |
| 2615 | |
| 2616 | # Rebase c0ffeee..deadbee onto c0ffeee |
| 2617 | # |
| 2618 | # Commands: |
| 2619 | # p, pick = use commit |
| 2620 | # r, reword = use commit, but edit the commit message |
| 2621 | # e, edit = use commit, but stop for amending |
| 2622 | # s, squash = use commit, but meld into previous commit |
| 2623 | # f, fixup = like "squash", but discard this commit's log message |
| 2624 | # x, exec = run command (the rest of the line) using shell |
| 2625 | # |
| 2626 | # These lines can be re-ordered; they are executed from top to bottom. |
| 2627 | # |
| 2628 | # If you remove a line here THAT COMMIT WILL BE LOST. |
| 2629 | # |
| 2630 | # However, if you remove everything, the rebase will be aborted. |
| 2631 | # |
| 2632 | # Note that empty commits are commented out |
| 2633 | ------------------------------------------------- |
| 2634 | |
| 2635 | As explained in the comments, you can reorder commits, squash them |
| 2636 | together, edit commit messages, etc. by editing the list. Once you |
| 2637 | are satisfied, save the list and close your editor, and the rebase |
| 2638 | will begin. |
| 2639 | |
| 2640 | The rebase will stop where `pick` has been replaced with `edit` or |
| 2641 | when a step in the list fails to mechanically resolve conflicts and |
| 2642 | needs your help. When you are done editing and/or resolving conflicts |
| 2643 | you can continue with `git rebase --continue`. If you decide that |
| 2644 | things are getting too hairy, you can always bail out with `git rebase |
| 2645 | --abort`. Even after the rebase is complete, you can still recover |
| 2646 | the original branch by using the <<reflogs,reflog>>. |
| 2647 | |
| 2648 | For a more detailed discussion of the procedure and additional tips, |
| 2649 | see the "INTERACTIVE MODE" section of linkgit:git-rebase[1]. |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2650 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 2651 | [[patch-series-tools]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 2652 | === Other tools |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2653 | |
Björn Gustavsson | 73a1d05 | 2009-11-22 10:47:04 +0100 | [diff] [blame] | 2654 | There are numerous other tools, such as StGit, which exist for the |
Michael Coleman | 79c96c5 | 2007-02-27 22:13:09 -0600 | [diff] [blame] | 2655 | purpose of maintaining a patch series. These are outside of the scope of |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2656 | this manual. |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2657 | |
Junio C Hamano | aa971cb | 2008-12-07 18:38:46 -0800 | [diff] [blame] | 2658 | [[problems-With-rewriting-history]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 2659 | === Problems with rewriting history |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2660 | |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2661 | The primary problem with rewriting the history of a branch has to do |
| 2662 | with merging. Suppose somebody fetches your branch and merges it into |
| 2663 | their branch, with a result something like this: |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2664 | |
J. Bruce Fields | 1dc71a9 | 2007-03-10 22:38:13 -0500 | [diff] [blame] | 2665 | ................................................ |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2666 | o--o--O--o--o--o <-- origin |
| 2667 | \ \ |
| 2668 | t--t--t--m <-- their branch: |
J. Bruce Fields | 1dc71a9 | 2007-03-10 22:38:13 -0500 | [diff] [blame] | 2669 | ................................................ |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2670 | |
| 2671 | Then suppose you modify the last three commits: |
| 2672 | |
J. Bruce Fields | 1dc71a9 | 2007-03-10 22:38:13 -0500 | [diff] [blame] | 2673 | ................................................ |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2674 | o--o--o <-- new head of origin |
| 2675 | / |
| 2676 | o--o--O--o--o--o <-- old head of origin |
J. Bruce Fields | 1dc71a9 | 2007-03-10 22:38:13 -0500 | [diff] [blame] | 2677 | ................................................ |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2678 | |
| 2679 | If we examined all this history together in one repository, it will |
| 2680 | look like: |
| 2681 | |
J. Bruce Fields | 1dc71a9 | 2007-03-10 22:38:13 -0500 | [diff] [blame] | 2682 | ................................................ |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2683 | o--o--o <-- new head of origin |
| 2684 | / |
| 2685 | o--o--O--o--o--o <-- old head of origin |
| 2686 | \ \ |
| 2687 | t--t--t--m <-- their branch: |
J. Bruce Fields | 1dc71a9 | 2007-03-10 22:38:13 -0500 | [diff] [blame] | 2688 | ................................................ |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2689 | |
| 2690 | Git has no way of knowing that the new head is an updated version of |
| 2691 | the old head; it treats this situation exactly the same as it would if |
| 2692 | two developers had independently done the work on the old and new heads |
| 2693 | in parallel. At this point, if someone attempts to merge the new head |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 2694 | in to their branch, Git will attempt to merge together the two (old and |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2695 | new) lines of development, instead of trying to replace the old by the |
| 2696 | new. The results are likely to be unexpected. |
| 2697 | |
| 2698 | You may still choose to publish branches whose history is rewritten, |
| 2699 | and it may be useful for others to be able to fetch those branches in |
| 2700 | order to examine or test them, but they should not attempt to pull such |
| 2701 | branches into their own work. |
| 2702 | |
| 2703 | For true distributed development that supports proper merging, |
| 2704 | published branches should never be rewritten. |
| 2705 | |
Steffen Prohaska | 3fb0028 | 2007-11-10 14:49:54 +0100 | [diff] [blame] | 2706 | [[bisect-merges]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 2707 | === Why bisecting merge commits can be harder than bisecting linear history |
Steffen Prohaska | 3fb0028 | 2007-11-10 14:49:54 +0100 | [diff] [blame] | 2708 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 2709 | The linkgit:git-bisect[1] command correctly handles history that |
Steffen Prohaska | 3fb0028 | 2007-11-10 14:49:54 +0100 | [diff] [blame] | 2710 | includes merge commits. However, when the commit that it finds is a |
| 2711 | merge commit, the user may need to work harder than usual to figure out |
| 2712 | why that commit introduced a problem. |
| 2713 | |
| 2714 | Imagine this history: |
| 2715 | |
| 2716 | ................................................ |
| 2717 | ---Z---o---X---...---o---A---C---D |
| 2718 | \ / |
| 2719 | o---o---Y---...---o---B |
| 2720 | ................................................ |
| 2721 | |
| 2722 | Suppose that on the upper line of development, the meaning of one |
| 2723 | of the functions that exists at Z is changed at commit X. The |
| 2724 | commits from Z leading to A change both the function's |
| 2725 | implementation and all calling sites that exist at Z, as well |
| 2726 | as new calling sites they add, to be consistent. There is no |
| 2727 | bug at A. |
| 2728 | |
| 2729 | Suppose that in the meantime on the lower line of development somebody |
| 2730 | adds a new calling site for that function at commit Y. The |
| 2731 | commits from Z leading to B all assume the old semantics of that |
| 2732 | function and the callers and the callee are consistent with each |
| 2733 | other. There is no bug at B, either. |
| 2734 | |
| 2735 | Suppose further that the two development lines merge cleanly at C, |
| 2736 | so no conflict resolution is required. |
| 2737 | |
| 2738 | Nevertheless, the code at C is broken, because the callers added |
| 2739 | on the lower line of development have not been converted to the new |
| 2740 | semantics introduced on the upper line of development. So if all |
| 2741 | you know is that D is bad, that Z is good, and that |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 2742 | linkgit:git-bisect[1] identifies C as the culprit, how will you |
Steffen Prohaska | 3fb0028 | 2007-11-10 14:49:54 +0100 | [diff] [blame] | 2743 | figure out that the problem is due to this change in semantics? |
| 2744 | |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 2745 | When the result of a `git bisect` is a non-merge commit, you should |
Steffen Prohaska | 3fb0028 | 2007-11-10 14:49:54 +0100 | [diff] [blame] | 2746 | normally be able to discover the problem by examining just that commit. |
| 2747 | Developers can make this easy by breaking their changes into small |
| 2748 | self-contained commits. That won't help in the case above, however, |
| 2749 | because the problem isn't obvious from examination of any single |
| 2750 | commit; instead, a global view of the development is required. To |
| 2751 | make matters worse, the change in semantics in the problematic |
| 2752 | function may be just one small part of the changes in the upper |
| 2753 | line of development. |
| 2754 | |
| 2755 | On the other hand, if instead of merging at C you had rebased the |
| 2756 | history between Z to B on top of A, you would have gotten this |
| 2757 | linear history: |
| 2758 | |
| 2759 | ................................................................ |
| 2760 | ---Z---o---X--...---o---A---o---o---Y*--...---o---B*--D* |
| 2761 | ................................................................ |
| 2762 | |
| 2763 | Bisecting between Z and D* would hit a single culprit commit Y*, |
| 2764 | and understanding why Y* was broken would probably be easier. |
| 2765 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 2766 | Partly for this reason, many experienced Git users, even when |
Steffen Prohaska | 3fb0028 | 2007-11-10 14:49:54 +0100 | [diff] [blame] | 2767 | working on an otherwise merge-heavy project, keep the history |
| 2768 | linear by rebasing against the latest upstream version before |
| 2769 | publishing. |
| 2770 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 2771 | [[advanced-branch-management]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 2772 | == Advanced branch management |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2773 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 2774 | [[fetching-individual-branches]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 2775 | === Fetching individual branches |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2776 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 2777 | Instead of using linkgit:git-remote[1], you can also choose just |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2778 | to update one branch at a time, and to store it locally under an |
| 2779 | arbitrary name: |
| 2780 | |
| 2781 | ------------------------------------------------- |
| 2782 | $ git fetch origin todo:my-todo-work |
| 2783 | ------------------------------------------------- |
| 2784 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 2785 | The first argument, `origin`, just tells Git to fetch from the |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 2786 | repository you originally cloned from. The second argument tells Git |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 2787 | to fetch the branch named `todo` from the remote repository, and to |
| 2788 | store it locally under the name `refs/heads/my-todo-work`. |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2789 | |
| 2790 | You can also fetch branches from other repositories; so |
| 2791 | |
| 2792 | ------------------------------------------------- |
| 2793 | $ git fetch git://example.com/proj.git master:example-master |
| 2794 | ------------------------------------------------- |
| 2795 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 2796 | will create a new branch named `example-master` and store in it the |
| 2797 | branch named `master` from the repository at the given URL. If you |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2798 | already have a branch named example-master, it will attempt to |
J. Bruce Fields | 5972304 | 2007-04-30 11:11:02 -0400 | [diff] [blame] | 2799 | <<fast-forwards,fast-forward>> to the commit given by example.com's |
| 2800 | master branch. In more detail: |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2801 | |
J. Bruce Fields | 5972304 | 2007-04-30 11:11:02 -0400 | [diff] [blame] | 2802 | [[fetch-fast-forwards]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 2803 | === git fetch and fast-forwards |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2804 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 2805 | In the previous example, when updating an existing branch, `git fetch` |
Jonathan Nieder | 7a7d4ef | 2008-07-03 00:20:21 -0500 | [diff] [blame] | 2806 | checks to make sure that the most recent commit on the remote |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2807 | branch is a descendant of the most recent commit on your copy of the |
| 2808 | branch before updating your copy of the branch to point at the new |
Felipe Contreras | a75d7b5 | 2009-10-24 11:31:32 +0300 | [diff] [blame] | 2809 | commit. Git calls this process a <<fast-forwards,fast-forward>>. |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2810 | |
Felipe Contreras | a75d7b5 | 2009-10-24 11:31:32 +0300 | [diff] [blame] | 2811 | A fast-forward looks something like this: |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2812 | |
J. Bruce Fields | 1dc71a9 | 2007-03-10 22:38:13 -0500 | [diff] [blame] | 2813 | ................................................ |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2814 | o--o--o--o <-- old head of the branch |
| 2815 | \ |
| 2816 | o--o--o <-- new head of the branch |
J. Bruce Fields | 1dc71a9 | 2007-03-10 22:38:13 -0500 | [diff] [blame] | 2817 | ................................................ |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2818 | |
| 2819 | |
| 2820 | In some cases it is possible that the new head will *not* actually be |
| 2821 | a descendant of the old head. For example, the developer may have |
Felipe Contreras | 69b3367 | 2021-06-15 14:11:09 +0000 | [diff] [blame] | 2822 | realized a serious mistake was made and decided to backtrack, |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2823 | resulting in a situation like: |
| 2824 | |
J. Bruce Fields | 1dc71a9 | 2007-03-10 22:38:13 -0500 | [diff] [blame] | 2825 | ................................................ |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2826 | o--o--o--o--a--b <-- old head of the branch |
| 2827 | \ |
| 2828 | o--o--o <-- new head of the branch |
J. Bruce Fields | 1dc71a9 | 2007-03-10 22:38:13 -0500 | [diff] [blame] | 2829 | ................................................ |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2830 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 2831 | In this case, `git fetch` will fail, and print out a warning. |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2832 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 2833 | In that case, you can still force Git to update to the new head, as |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2834 | described in the following section. However, note that in the |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 2835 | situation above this may mean losing the commits labeled `a` and `b`, |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2836 | unless you've already created a reference of your own pointing to |
| 2837 | them. |
| 2838 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 2839 | [[forcing-fetch]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 2840 | === Forcing git fetch to do non-fast-forward updates |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2841 | |
| 2842 | If git fetch fails because the new head of a branch is not a |
| 2843 | descendant of the old head, you may force the update with: |
| 2844 | |
| 2845 | ------------------------------------------------- |
| 2846 | $ git fetch git://example.com/proj.git +master:refs/remotes/example/master |
| 2847 | ------------------------------------------------- |
| 2848 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 2849 | Note the addition of the `+` sign. Alternatively, you can use the `-f` |
J. Bruce Fields | c64415e | 2007-05-07 00:56:45 -0400 | [diff] [blame] | 2850 | flag to force updates of all the fetched branches, as in: |
| 2851 | |
| 2852 | ------------------------------------------------- |
| 2853 | $ git fetch -f origin |
| 2854 | ------------------------------------------------- |
| 2855 | |
| 2856 | Be aware that commits that the old version of example/master pointed at |
| 2857 | may be lost, as we saw in the previous section. |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2858 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 2859 | [[remote-branch-configuration]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 2860 | === Configuring remote-tracking branches |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2861 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 2862 | We saw above that `origin` is just a shortcut to refer to the |
Michael Coleman | 79c96c5 | 2007-02-27 22:13:09 -0600 | [diff] [blame] | 2863 | repository that you originally cloned from. This information is |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 2864 | stored in Git configuration variables, which you can see using |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 2865 | linkgit:git-config[1]: |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2866 | |
| 2867 | ------------------------------------------------- |
J. Bruce Fields | 9d13bda | 2007-01-28 23:50:22 -0500 | [diff] [blame] | 2868 | $ git config -l |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2869 | core.repositoryformatversion=0 |
| 2870 | core.filemode=true |
| 2871 | core.logallrefupdates=true |
| 2872 | remote.origin.url=git://git.kernel.org/pub/scm/git/git.git |
| 2873 | remote.origin.fetch=+refs/heads/*:refs/remotes/origin/* |
| 2874 | branch.master.remote=origin |
| 2875 | branch.master.merge=refs/heads/master |
| 2876 | ------------------------------------------------- |
| 2877 | |
| 2878 | If there are other repositories that you also use frequently, you can |
| 2879 | create similar configuration options to save typing; for example, |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2880 | |
| 2881 | ------------------------------------------------- |
W. Trevor King | 47adb8a | 2013-02-17 19:15:56 -0500 | [diff] [blame] | 2882 | $ git remote add example git://example.com/proj.git |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2883 | ------------------------------------------------- |
| 2884 | |
W. Trevor King | 47adb8a | 2013-02-17 19:15:56 -0500 | [diff] [blame] | 2885 | adds the following to `.git/config`: |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2886 | |
| 2887 | ------------------------------------------------- |
W. Trevor King | 47adb8a | 2013-02-17 19:15:56 -0500 | [diff] [blame] | 2888 | [remote "example"] |
| 2889 | url = git://example.com/proj.git |
| 2890 | fetch = +refs/heads/*:refs/remotes/example/* |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2891 | ------------------------------------------------- |
| 2892 | |
W. Trevor King | 47adb8a | 2013-02-17 19:15:56 -0500 | [diff] [blame] | 2893 | Also note that the above configuration can be performed by directly |
| 2894 | editing the file `.git/config` instead of using linkgit:git-remote[1]. |
| 2895 | |
| 2896 | After configuring the remote, the following three commands will do the |
| 2897 | same thing: |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2898 | |
| 2899 | ------------------------------------------------- |
W. Trevor King | 47adb8a | 2013-02-17 19:15:56 -0500 | [diff] [blame] | 2900 | $ git fetch git://example.com/proj.git +refs/heads/*:refs/remotes/example/* |
| 2901 | $ git fetch example +refs/heads/*:refs/remotes/example/* |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2902 | $ git fetch example |
| 2903 | ------------------------------------------------- |
| 2904 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 2905 | See linkgit:git-config[1] for more details on the configuration |
W. Trevor King | 47adb8a | 2013-02-17 19:15:56 -0500 | [diff] [blame] | 2906 | options mentioned above and linkgit:git-fetch[1] for more details on |
| 2907 | the refspec syntax. |
J. Bruce Fields | 4c63ff4 | 2007-01-07 23:57:41 -0500 | [diff] [blame] | 2908 | |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 2909 | |
J. Bruce Fields | 036f819 | 2007-08-30 23:10:05 -0400 | [diff] [blame] | 2910 | [[git-concepts]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 2911 | == Git concepts |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 2912 | |
J. Bruce Fields | 036f819 | 2007-08-30 23:10:05 -0400 | [diff] [blame] | 2913 | Git is built on a small number of simple but powerful ideas. While it |
| 2914 | is possible to get things done without understanding them, you will find |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 2915 | Git much more intuitive if you do. |
J. Bruce Fields | 036f819 | 2007-08-30 23:10:05 -0400 | [diff] [blame] | 2916 | |
| 2917 | We start with the most important, the <<def_object_database,object |
| 2918 | database>> and the <<def_index,index>>. |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2919 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 2920 | [[the-object-database]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 2921 | === The Object Database |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2922 | |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2923 | |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 2924 | We already saw in <<understanding-commits>> that all commits are stored |
| 2925 | under a 40-digit "object name". In fact, all the information needed to |
| 2926 | represent the history of a project is stored in objects with such names. |
Felipe Contreras | a6e5ef7 | 2009-04-04 12:38:27 +0300 | [diff] [blame] | 2927 | In each case the name is calculated by taking the SHA-1 hash of the |
| 2928 | contents of the object. The SHA-1 hash is a cryptographic hash function. |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 2929 | What that means to us is that it is impossible to find two different |
| 2930 | objects with the same name. This has a number of advantages; among |
| 2931 | others: |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2932 | |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 2933 | - Git can quickly determine whether two objects are identical or not, |
| 2934 | just by comparing names. |
Ralf Wildenhues | 06ada15 | 2007-10-09 23:00:03 +0200 | [diff] [blame] | 2935 | - Since object names are computed the same way in every repository, the |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 2936 | same content stored in two repositories will always be stored under |
| 2937 | the same name. |
| 2938 | - Git can detect errors when it reads an object, by checking that the |
Felipe Contreras | a6e5ef7 | 2009-04-04 12:38:27 +0300 | [diff] [blame] | 2939 | object's name is still the SHA-1 hash of its contents. |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2940 | |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 2941 | (See <<object-details>> for the details of the object formatting and |
Felipe Contreras | a6e5ef7 | 2009-04-04 12:38:27 +0300 | [diff] [blame] | 2942 | SHA-1 calculation.) |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2943 | |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 2944 | There are four different types of objects: "blob", "tree", "commit", and |
| 2945 | "tag". |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2946 | |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 2947 | - A <<def_blob_object,"blob" object>> is used to store file data. |
Eric Hanchrow | 843c81d | 2008-07-08 13:00:30 -0700 | [diff] [blame] | 2948 | - A <<def_tree_object,"tree" object>> ties one or more |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 2949 | "blob" objects into a directory structure. In addition, a tree object |
| 2950 | can refer to other tree objects, thus creating a directory hierarchy. |
| 2951 | - A <<def_commit_object,"commit" object>> ties such directory hierarchies |
Ralf Wildenhues | 2ef8ac1 | 2007-10-09 23:05:30 +0200 | [diff] [blame] | 2952 | together into a <<def_DAG,directed acyclic graph>> of revisions--each |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 2953 | commit contains the object name of exactly one tree designating the |
| 2954 | directory hierarchy at the time of the commit. In addition, a commit |
| 2955 | refers to "parent" commit objects that describe the history of how we |
| 2956 | arrived at that directory hierarchy. |
| 2957 | - A <<def_tag_object,"tag" object>> symbolically identifies and can be |
| 2958 | used to sign other objects. It contains the object name and type of |
| 2959 | another object, a symbolic name (of course!) and, optionally, a |
| 2960 | signature. |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2961 | |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2962 | The object types in some more detail: |
| 2963 | |
J. Bruce Fields | 513d419 | 2007-08-31 23:26:38 -0400 | [diff] [blame] | 2964 | [[commit-object]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 2965 | ==== Commit Object |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2966 | |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 2967 | The "commit" object links a physical state of a tree with a description |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 2968 | of how we got there and why. Use the `--pretty=raw` option to |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 2969 | linkgit:git-show[1] or linkgit:git-log[1] to examine your favorite |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 2970 | commit: |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2971 | |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 2972 | ------------------------------------------------ |
| 2973 | $ git show -s --pretty=raw 2be7fcb476 |
| 2974 | commit 2be7fcb4764f2dbcee52635b91fedb1b3dcf7ab4 |
| 2975 | tree fb3a8bdd0ceddd019615af4d57a53f43d8cee2bf |
| 2976 | parent 257a84d9d02e90447b149af58b271c19405edb6a |
| 2977 | author Dave Watson <dwatson@mimvista.com> 1187576872 -0400 |
| 2978 | committer Junio C Hamano <gitster@pobox.com> 1187591163 -0700 |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 2979 | |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 2980 | Fix misspelling of 'suppress' in docs |
J. Bruce Fields | 513d419 | 2007-08-31 23:26:38 -0400 | [diff] [blame] | 2981 | |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 2982 | Signed-off-by: Junio C Hamano <gitster@pobox.com> |
| 2983 | ------------------------------------------------ |
| 2984 | |
| 2985 | As you can see, a commit is defined by: |
| 2986 | |
Felipe Contreras | a6e5ef7 | 2009-04-04 12:38:27 +0300 | [diff] [blame] | 2987 | - a tree: The SHA-1 name of a tree object (as defined below), representing |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 2988 | the contents of a directory at a certain point in time. |
Štěpán Němec | edfbbf7 | 2012-07-15 00:20:36 +0200 | [diff] [blame] | 2989 | - parent(s): The SHA-1 name(s) of some number of commits which represent the |
Shawn Bohrer | 9e5d87d | 2007-12-12 22:36:21 -0600 | [diff] [blame] | 2990 | immediately previous step(s) in the history of the project. The |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 2991 | example above has one parent; merge commits may have more than |
| 2992 | one. A commit with no parents is called a "root" commit, and |
| 2993 | represents the initial revision of a project. Each project must have |
| 2994 | at least one root. A project can also have multiple roots, though |
| 2995 | that isn't common (or necessarily a good idea). |
| 2996 | - an author: The name of the person responsible for this change, together |
| 2997 | with its date. |
| 2998 | - a committer: The name of the person who actually created the commit, |
| 2999 | with the date it was done. This may be different from the author, for |
| 3000 | example, if the author was someone who wrote a patch and emailed it |
| 3001 | to the person who used it to create the commit. |
| 3002 | - a comment describing this commit. |
| 3003 | |
| 3004 | Note that a commit does not itself contain any information about what |
| 3005 | actually changed; all changes are calculated by comparing the contents |
| 3006 | of the tree referred to by this commit with the trees associated with |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 3007 | its parents. In particular, Git does not attempt to record file renames |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 3008 | explicitly, though it can identify cases where the existence of the same |
| 3009 | file data at changing paths suggests a rename. (See, for example, the |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 3010 | `-M` option to linkgit:git-diff[1]). |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 3011 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 3012 | A commit is usually created by linkgit:git-commit[1], which creates a |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 3013 | commit whose parent is normally the current HEAD, and whose tree is |
| 3014 | taken from the content currently stored in the index. |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3015 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 3016 | [[tree-object]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 3017 | ==== Tree Object |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3018 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 3019 | The ever-versatile linkgit:git-show[1] command can also be used to |
| 3020 | examine tree objects, but linkgit:git-ls-tree[1] will give you more |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 3021 | details: |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3022 | |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 3023 | ------------------------------------------------ |
| 3024 | $ git ls-tree fb3a8bdd0ce |
| 3025 | 100644 blob 63c918c667fa005ff12ad89437f2fdc80926e21c .gitignore |
| 3026 | 100644 blob 5529b198e8d14decbe4ad99db3f7fb632de0439d .mailmap |
| 3027 | 100644 blob 6ff87c4664981e4397625791c8ea3bbb5f2279a3 COPYING |
| 3028 | 040000 tree 2fb783e477100ce076f6bf57e4a6f026013dc745 Documentation |
| 3029 | 100755 blob 3c0032cec592a765692234f1cba47dfdcc3a9200 GIT-VERSION-GEN |
| 3030 | 100644 blob 289b046a443c0647624607d471289b2c7dcd470b INSTALL |
| 3031 | 100644 blob 4eb463797adc693dc168b926b6932ff53f17d0b1 Makefile |
| 3032 | 100644 blob 548142c327a6790ff8821d67c2ee1eff7a656b52 README |
| 3033 | ... |
| 3034 | ------------------------------------------------ |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3035 | |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 3036 | As you can see, a tree object contains a list of entries, each with a |
Felipe Contreras | a6e5ef7 | 2009-04-04 12:38:27 +0300 | [diff] [blame] | 3037 | mode, object type, SHA-1 name, and name, sorted by name. It represents |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 3038 | the contents of a single directory tree. |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3039 | |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 3040 | The object type may be a blob, representing the contents of a file, or |
| 3041 | another tree, representing the contents of a subdirectory. Since trees |
Felipe Contreras | a6e5ef7 | 2009-04-04 12:38:27 +0300 | [diff] [blame] | 3042 | and blobs, like all other objects, are named by the SHA-1 hash of their |
| 3043 | contents, two trees have the same SHA-1 name if and only if their |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 3044 | contents (including, recursively, the contents of all subdirectories) |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 3045 | are identical. This allows Git to quickly determine the differences |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 3046 | between two related tree objects, since it can ignore any entries with |
| 3047 | identical object names. |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3048 | |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 3049 | (Note: in the presence of submodules, trees may also have commits as |
Michael Smith | 6dd1436 | 2007-09-25 08:44:38 -0400 | [diff] [blame] | 3050 | entries. See <<submodules>> for documentation.) |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3051 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 3052 | Note that the files all have mode 644 or 755: Git actually only pays |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 3053 | attention to the executable bit. |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3054 | |
J. Bruce Fields | 513d419 | 2007-08-31 23:26:38 -0400 | [diff] [blame] | 3055 | [[blob-object]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 3056 | ==== Blob Object |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3057 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 3058 | You can use linkgit:git-show[1] to examine the contents of a blob; take, |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 3059 | for example, the blob in the entry for `COPYING` from the tree above: |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3060 | |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 3061 | ------------------------------------------------ |
| 3062 | $ git show 6ff87c4664 |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3063 | |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 3064 | Note that the only valid version of the GPL as far as this project |
| 3065 | is concerned is _this_ particular version of the license (ie v2, not |
| 3066 | v2.2 or v3.x or whatever), unless explicitly otherwise stated. |
| 3067 | ... |
| 3068 | ------------------------------------------------ |
| 3069 | |
| 3070 | A "blob" object is nothing but a binary blob of data. It doesn't refer |
| 3071 | to anything else or have attributes of any kind. |
| 3072 | |
| 3073 | Since the blob is entirely defined by its data, if two files in a |
| 3074 | directory tree (or in multiple different versions of the repository) |
| 3075 | have the same contents, they will share the same blob object. The object |
| 3076 | is totally independent of its location in the directory tree, and |
| 3077 | renaming a file does not change the object that file is associated with. |
| 3078 | |
| 3079 | Note that any tree or blob object can be examined using |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 3080 | linkgit:git-show[1] with the <revision>:<path> syntax. This can |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 3081 | sometimes be useful for browsing the contents of a tree that is not |
| 3082 | currently checked out. |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3083 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 3084 | [[trust]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 3085 | ==== Trust |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3086 | |
Felipe Contreras | a6e5ef7 | 2009-04-04 12:38:27 +0300 | [diff] [blame] | 3087 | If you receive the SHA-1 name of a blob from one source, and its contents |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 3088 | from another (possibly untrusted) source, you can still trust that those |
Felipe Contreras | a6e5ef7 | 2009-04-04 12:38:27 +0300 | [diff] [blame] | 3089 | contents are correct as long as the SHA-1 name agrees. This is because |
| 3090 | the SHA-1 is designed so that it is infeasible to find different contents |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 3091 | that produce the same hash. |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3092 | |
Felipe Contreras | a6e5ef7 | 2009-04-04 12:38:27 +0300 | [diff] [blame] | 3093 | Similarly, you need only trust the SHA-1 name of a top-level tree object |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 3094 | to trust the contents of the entire directory that it refers to, and if |
Felipe Contreras | a6e5ef7 | 2009-04-04 12:38:27 +0300 | [diff] [blame] | 3095 | you receive the SHA-1 name of a commit from a trusted source, then you |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 3096 | can easily verify the entire history of commits reachable through |
| 3097 | parents of that commit, and all of those contents of the trees referred |
| 3098 | to by those commits. |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3099 | |
| 3100 | So to introduce some real trust in the system, the only thing you need |
| 3101 | to do is to digitally sign just 'one' special note, which includes the |
| 3102 | name of a top-level commit. Your digital signature shows others |
| 3103 | that you trust that commit, and the immutability of the history of |
| 3104 | commits tells others that they can trust the whole history. |
| 3105 | |
| 3106 | In other words, you can easily validate a whole archive by just |
Felipe Contreras | a6e5ef7 | 2009-04-04 12:38:27 +0300 | [diff] [blame] | 3107 | sending out a single email that tells the people the name (SHA-1 hash) |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3108 | of the top commit, and digitally sign that email using something |
| 3109 | like GPG/PGP. |
| 3110 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 3111 | To assist in this, Git also provides the tag object... |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3112 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 3113 | [[tag-object]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 3114 | ==== Tag Object |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3115 | |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 3116 | A tag object contains an object, object type, tag name, the name of the |
| 3117 | person ("tagger") who created the tag, and a message, which may contain |
Eric Hanchrow | 843c81d | 2008-07-08 13:00:30 -0700 | [diff] [blame] | 3118 | a signature, as can be seen using linkgit:git-cat-file[1]: |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3119 | |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 3120 | ------------------------------------------------ |
| 3121 | $ git cat-file tag v1.5.0 |
| 3122 | object 437b1b20df4b356c9342dac8d38849f24ef44f27 |
| 3123 | type commit |
| 3124 | tag v1.5.0 |
| 3125 | tagger Junio C Hamano <junkio@cox.net> 1171411200 +0000 |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3126 | |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 3127 | GIT 1.5.0 |
| 3128 | -----BEGIN PGP SIGNATURE----- |
| 3129 | Version: GnuPG v1.4.6 (GNU/Linux) |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3130 | |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 3131 | iD8DBQBF0lGqwMbZpPMRm5oRAuRiAJ9ohBLd7s2kqjkKlq1qqC57SbnmzQCdG4ui |
| 3132 | nLE/L9aUXdWeTFPron96DLA= |
| 3133 | =2E+0 |
| 3134 | -----END PGP SIGNATURE----- |
| 3135 | ------------------------------------------------ |
| 3136 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 3137 | See the linkgit:git-tag[1] command to learn how to create and verify tag |
| 3138 | objects. (Note that linkgit:git-tag[1] can also be used to create |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 3139 | "lightweight tags", which are not tag objects at all, but just simple |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 3140 | references whose names begin with `refs/tags/`). |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3141 | |
J. Bruce Fields | 09eff7b | 2007-09-08 22:13:53 -0400 | [diff] [blame] | 3142 | [[pack-files]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 3143 | ==== How Git stores objects efficiently: pack files |
J. Bruce Fields | 09eff7b | 2007-09-08 22:13:53 -0400 | [diff] [blame] | 3144 | |
J. Bruce Fields | 9644ffd | 2007-09-08 22:27:18 -0400 | [diff] [blame] | 3145 | Newly created objects are initially created in a file named after the |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 3146 | object's SHA-1 hash (stored in `.git/objects`). |
J. Bruce Fields | 09eff7b | 2007-09-08 22:13:53 -0400 | [diff] [blame] | 3147 | |
| 3148 | Unfortunately this system becomes inefficient once a project has a |
| 3149 | lot of objects. Try this on an old project: |
| 3150 | |
| 3151 | ------------------------------------------------ |
| 3152 | $ git count-objects |
| 3153 | 6930 objects, 47620 kilobytes |
| 3154 | ------------------------------------------------ |
| 3155 | |
| 3156 | The first number is the number of objects which are kept in |
| 3157 | individual files. The second is the amount of space taken up by |
| 3158 | those "loose" objects. |
| 3159 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 3160 | You can save space and make Git faster by moving these loose objects in |
J. Bruce Fields | 09eff7b | 2007-09-08 22:13:53 -0400 | [diff] [blame] | 3161 | to a "pack file", which stores a group of objects in an efficient |
| 3162 | compressed format; the details of how pack files are formatted can be |
Todd Zullinger | 086eaab | 2022-09-16 02:23:02 -0400 | [diff] [blame] | 3163 | found in linkgit:gitformat-pack[5]. |
J. Bruce Fields | 09eff7b | 2007-09-08 22:13:53 -0400 | [diff] [blame] | 3164 | |
| 3165 | To put the loose objects into a pack, just run git repack: |
| 3166 | |
| 3167 | ------------------------------------------------ |
| 3168 | $ git repack |
Thomas Ackermann | 3e65ac4 | 2013-08-27 19:56:50 +0200 | [diff] [blame] | 3169 | Counting objects: 6020, done. |
| 3170 | Delta compression using up to 4 threads. |
| 3171 | Compressing objects: 100% (6020/6020), done. |
| 3172 | Writing objects: 100% (6020/6020), done. |
| 3173 | Total 6020 (delta 4070), reused 0 (delta 0) |
J. Bruce Fields | 09eff7b | 2007-09-08 22:13:53 -0400 | [diff] [blame] | 3174 | ------------------------------------------------ |
| 3175 | |
Thomas Ackermann | 3e65ac4 | 2013-08-27 19:56:50 +0200 | [diff] [blame] | 3176 | This creates a single "pack file" in .git/objects/pack/ |
| 3177 | containing all currently unpacked objects. You can then run |
J. Bruce Fields | 09eff7b | 2007-09-08 22:13:53 -0400 | [diff] [blame] | 3178 | |
| 3179 | ------------------------------------------------ |
| 3180 | $ git prune |
| 3181 | ------------------------------------------------ |
| 3182 | |
| 3183 | to remove any of the "loose" objects that are now contained in the |
| 3184 | pack. This will also remove any unreferenced objects (which may be |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 3185 | created when, for example, you use `git reset` to remove a commit). |
J. Bruce Fields | 09eff7b | 2007-09-08 22:13:53 -0400 | [diff] [blame] | 3186 | You can verify that the loose objects are gone by looking at the |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 3187 | `.git/objects` directory or by running |
J. Bruce Fields | 09eff7b | 2007-09-08 22:13:53 -0400 | [diff] [blame] | 3188 | |
| 3189 | ------------------------------------------------ |
| 3190 | $ git count-objects |
| 3191 | 0 objects, 0 kilobytes |
| 3192 | ------------------------------------------------ |
| 3193 | |
| 3194 | Although the object files are gone, any commands that refer to those |
| 3195 | objects will work exactly as they did before. |
| 3196 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 3197 | The linkgit:git-gc[1] command performs packing, pruning, and more for |
J. Bruce Fields | 09eff7b | 2007-09-08 22:13:53 -0400 | [diff] [blame] | 3198 | you, so is normally the only high-level command you need. |
| 3199 | |
| 3200 | [[dangling-objects]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 3201 | ==== Dangling objects |
J. Bruce Fields | 09eff7b | 2007-09-08 22:13:53 -0400 | [diff] [blame] | 3202 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 3203 | The linkgit:git-fsck[1] command will sometimes complain about dangling |
J. Bruce Fields | 09eff7b | 2007-09-08 22:13:53 -0400 | [diff] [blame] | 3204 | objects. They are not a problem. |
| 3205 | |
| 3206 | The most common cause of dangling objects is that you've rebased a |
| 3207 | branch, or you have pulled from somebody else who rebased a branch--see |
| 3208 | <<cleaning-up-history>>. In that case, the old head of the original |
| 3209 | branch still exists, as does everything it pointed to. The branch |
| 3210 | pointer itself just doesn't, since you replaced it with another one. |
| 3211 | |
| 3212 | There are also other situations that cause dangling objects. For |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 3213 | example, a "dangling blob" may arise because you did a `git add` of a |
J. Bruce Fields | 09eff7b | 2007-09-08 22:13:53 -0400 | [diff] [blame] | 3214 | file, but then, before you actually committed it and made it part of the |
| 3215 | bigger picture, you changed something else in that file and committed |
Ralf Wildenhues | 2ef8ac1 | 2007-10-09 23:05:30 +0200 | [diff] [blame] | 3216 | that *updated* thing--the old state that you added originally ends up |
J. Bruce Fields | 09eff7b | 2007-09-08 22:13:53 -0400 | [diff] [blame] | 3217 | not being pointed to by any commit or tree, so it's now a dangling blob |
| 3218 | object. |
| 3219 | |
Elijah Newren | f5a3c5e | 2021-08-04 05:38:02 +0000 | [diff] [blame] | 3220 | Similarly, when the "ort" merge strategy runs, and finds that |
J. Bruce Fields | 09eff7b | 2007-09-08 22:13:53 -0400 | [diff] [blame] | 3221 | there are criss-cross merges and thus more than one merge base (which is |
| 3222 | fairly unusual, but it does happen), it will generate one temporary |
| 3223 | midway tree (or possibly even more, if you had lots of criss-crossing |
| 3224 | merges and more than two merge bases) as a temporary internal merge |
| 3225 | base, and again, those are real objects, but the end result will not end |
| 3226 | up pointing to them, so they end up "dangling" in your repository. |
| 3227 | |
| 3228 | Generally, dangling objects aren't anything to worry about. They can |
| 3229 | even be very useful: if you screw something up, the dangling objects can |
| 3230 | be how you recover your old tree (say, you did a rebase, and realized |
Ralf Wildenhues | 2ef8ac1 | 2007-10-09 23:05:30 +0200 | [diff] [blame] | 3231 | that you really didn't want to--you can look at what dangling objects |
J. Bruce Fields | 09eff7b | 2007-09-08 22:13:53 -0400 | [diff] [blame] | 3232 | you have, and decide to reset your head to some old dangling state). |
| 3233 | |
| 3234 | For commits, you can just use: |
| 3235 | |
| 3236 | ------------------------------------------------ |
| 3237 | $ gitk <dangling-commit-sha-goes-here> --not --all |
| 3238 | ------------------------------------------------ |
| 3239 | |
| 3240 | This asks for all the history reachable from the given commit but not |
| 3241 | from any branch, tag, or other reference. If you decide it's something |
| 3242 | you want, you can always create a new reference to it, e.g., |
| 3243 | |
| 3244 | ------------------------------------------------ |
| 3245 | $ git branch recovered-branch <dangling-commit-sha-goes-here> |
| 3246 | ------------------------------------------------ |
| 3247 | |
| 3248 | For blobs and trees, you can't do the same, but you can still examine |
| 3249 | them. You can just do |
| 3250 | |
| 3251 | ------------------------------------------------ |
| 3252 | $ git show <dangling-blob/tree-sha-goes-here> |
| 3253 | ------------------------------------------------ |
| 3254 | |
| 3255 | to show what the contents of the blob were (or, for a tree, basically |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 3256 | what the `ls` for that directory was), and that may give you some idea |
J. Bruce Fields | 09eff7b | 2007-09-08 22:13:53 -0400 | [diff] [blame] | 3257 | of what the operation was that left that dangling object. |
| 3258 | |
| 3259 | Usually, dangling blobs and trees aren't very interesting. They're |
| 3260 | almost always the result of either being a half-way mergebase (the blob |
| 3261 | will often even have the conflict markers from a merge in it, if you |
| 3262 | have had conflicting merges that you fixed up by hand), or simply |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 3263 | because you interrupted a `git fetch` with ^C or something like that, |
J. Bruce Fields | 09eff7b | 2007-09-08 22:13:53 -0400 | [diff] [blame] | 3264 | leaving _some_ of the new objects in the object database, but just |
| 3265 | dangling and useless. |
| 3266 | |
| 3267 | Anyway, once you are sure that you're not interested in any dangling |
| 3268 | state, you can just prune all unreachable objects: |
| 3269 | |
| 3270 | ------------------------------------------------ |
| 3271 | $ git prune |
| 3272 | ------------------------------------------------ |
| 3273 | |
Thomas Ackermann | ddeb817 | 2013-08-27 20:05:50 +0200 | [diff] [blame] | 3274 | and they'll be gone. (You should only run `git prune` on a quiescent |
Ralf Wildenhues | 2ef8ac1 | 2007-10-09 23:05:30 +0200 | [diff] [blame] | 3275 | repository--it's kind of like doing a filesystem fsck recovery: you |
J. Bruce Fields | 09eff7b | 2007-09-08 22:13:53 -0400 | [diff] [blame] | 3276 | don't want to do that while the filesystem is mounted. |
Thomas Ackermann | ddeb817 | 2013-08-27 20:05:50 +0200 | [diff] [blame] | 3277 | `git prune` is designed not to cause any harm in such cases of concurrent |
| 3278 | accesses to a repository but you might receive confusing or scary messages.) |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3279 | |
J. Bruce Fields | 1cdade2 | 2007-03-03 22:53:37 -0500 | [diff] [blame] | 3280 | [[recovering-from-repository-corruption]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 3281 | ==== Recovering from repository corruption |
J. Bruce Fields | 1cdade2 | 2007-03-03 22:53:37 -0500 | [diff] [blame] | 3282 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 3283 | By design, Git treats data trusted to it with caution. However, even in |
| 3284 | the absence of bugs in Git itself, it is still possible that hardware or |
J. Bruce Fields | 1cdade2 | 2007-03-03 22:53:37 -0500 | [diff] [blame] | 3285 | operating system errors could corrupt data. |
| 3286 | |
| 3287 | The first defense against such problems is backups. You can back up a |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 3288 | Git directory using clone, or just using cp, tar, or any other backup |
J. Bruce Fields | 1cdade2 | 2007-03-03 22:53:37 -0500 | [diff] [blame] | 3289 | mechanism. |
| 3290 | |
| 3291 | As a last resort, you can search for the corrupted objects and attempt |
| 3292 | to replace them by hand. Back up your repository before attempting this |
| 3293 | in case you corrupt things even more in the process. |
| 3294 | |
| 3295 | We'll assume that the problem is a single missing or corrupted blob, |
Shawn Bohrer | 9e5d87d | 2007-12-12 22:36:21 -0600 | [diff] [blame] | 3296 | which is sometimes a solvable problem. (Recovering missing trees and |
J. Bruce Fields | 1cdade2 | 2007-03-03 22:53:37 -0500 | [diff] [blame] | 3297 | especially commits is *much* harder). |
| 3298 | |
| 3299 | Before starting, verify that there is corruption, and figure out where |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 3300 | it is with linkgit:git-fsck[1]; this may be time-consuming. |
J. Bruce Fields | 1cdade2 | 2007-03-03 22:53:37 -0500 | [diff] [blame] | 3301 | |
| 3302 | Assume the output looks like this: |
| 3303 | |
| 3304 | ------------------------------------------------ |
Junio C Hamano | c6a13b2 | 2012-02-28 14:55:39 -0800 | [diff] [blame] | 3305 | $ git fsck --full --no-dangling |
J. Bruce Fields | 1cdade2 | 2007-03-03 22:53:37 -0500 | [diff] [blame] | 3306 | broken link from tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8 |
| 3307 | to blob 4b9458b3786228369c63936db65827de3cc06200 |
| 3308 | missing blob 4b9458b3786228369c63936db65827de3cc06200 |
| 3309 | ------------------------------------------------ |
| 3310 | |
J. Bruce Fields | 1cdade2 | 2007-03-03 22:53:37 -0500 | [diff] [blame] | 3311 | Now you know that blob 4b9458b3 is missing, and that the tree 2d9263c6 |
| 3312 | points to it. If you could find just one copy of that missing blob |
| 3313 | object, possibly in some other repository, you could move it into |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 3314 | `.git/objects/4b/9458b3...` and be done. Suppose you can't. You can |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 3315 | still examine the tree that pointed to it with linkgit:git-ls-tree[1], |
J. Bruce Fields | 1cdade2 | 2007-03-03 22:53:37 -0500 | [diff] [blame] | 3316 | which might output something like: |
| 3317 | |
| 3318 | ------------------------------------------------ |
| 3319 | $ git ls-tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8 |
| 3320 | 100644 blob 8d14531846b95bfa3564b58ccfb7913a034323b8 .gitignore |
| 3321 | 100644 blob ebf9bf84da0aab5ed944264a5db2a65fe3a3e883 .mailmap |
| 3322 | 100644 blob ca442d313d86dc67e0a2e5d584b465bd382cbf5c COPYING |
| 3323 | ... |
| 3324 | 100644 blob 4b9458b3786228369c63936db65827de3cc06200 myfile |
| 3325 | ... |
| 3326 | ------------------------------------------------ |
| 3327 | |
| 3328 | So now you know that the missing blob was the data for a file named |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 3329 | `myfile`. And chances are you can also identify the directory--let's |
| 3330 | say it's in `somedirectory`. If you're lucky the missing copy might be |
J. Bruce Fields | 1cdade2 | 2007-03-03 22:53:37 -0500 | [diff] [blame] | 3331 | the same as the copy you have checked out in your working tree at |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 3332 | `somedirectory/myfile`; you can test whether that's right with |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 3333 | linkgit:git-hash-object[1]: |
J. Bruce Fields | 1cdade2 | 2007-03-03 22:53:37 -0500 | [diff] [blame] | 3334 | |
| 3335 | ------------------------------------------------ |
| 3336 | $ git hash-object -w somedirectory/myfile |
| 3337 | ------------------------------------------------ |
| 3338 | |
| 3339 | which will create and store a blob object with the contents of |
Felipe Contreras | a6e5ef7 | 2009-04-04 12:38:27 +0300 | [diff] [blame] | 3340 | somedirectory/myfile, and output the SHA-1 of that object. if you're |
J. Bruce Fields | 1cdade2 | 2007-03-03 22:53:37 -0500 | [diff] [blame] | 3341 | extremely lucky it might be 4b9458b3786228369c63936db65827de3cc06200, in |
| 3342 | which case you've guessed right, and the corruption is fixed! |
| 3343 | |
| 3344 | Otherwise, you need more information. How do you tell which version of |
| 3345 | the file has been lost? |
| 3346 | |
| 3347 | The easiest way to do this is with: |
| 3348 | |
| 3349 | ------------------------------------------------ |
| 3350 | $ git log --raw --all --full-history -- somedirectory/myfile |
| 3351 | ------------------------------------------------ |
| 3352 | |
| 3353 | Because you're asking for raw output, you'll now get something like |
| 3354 | |
| 3355 | ------------------------------------------------ |
| 3356 | commit abc |
| 3357 | Author: |
| 3358 | Date: |
| 3359 | ... |
Ann T Ropea | f61d89e | 2017-12-03 22:27:38 +0100 | [diff] [blame] | 3360 | :100644 100644 4b9458b newsha M somedirectory/myfile |
J. Bruce Fields | 1cdade2 | 2007-03-03 22:53:37 -0500 | [diff] [blame] | 3361 | |
| 3362 | |
| 3363 | commit xyz |
| 3364 | Author: |
| 3365 | Date: |
| 3366 | |
| 3367 | ... |
Ann T Ropea | f61d89e | 2017-12-03 22:27:38 +0100 | [diff] [blame] | 3368 | :100644 100644 oldsha 4b9458b M somedirectory/myfile |
J. Bruce Fields | 1cdade2 | 2007-03-03 22:53:37 -0500 | [diff] [blame] | 3369 | ------------------------------------------------ |
| 3370 | |
Štěpán Němec | edfbbf7 | 2012-07-15 00:20:36 +0200 | [diff] [blame] | 3371 | This tells you that the immediately following version of the file was |
| 3372 | "newsha", and that the immediately preceding version was "oldsha". |
J. Bruce Fields | 1cdade2 | 2007-03-03 22:53:37 -0500 | [diff] [blame] | 3373 | You also know the commit messages that went with the change from oldsha |
| 3374 | to 4b9458b and with the change from 4b9458b to newsha. |
| 3375 | |
| 3376 | If you've been committing small enough changes, you may now have a good |
| 3377 | shot at reconstructing the contents of the in-between state 4b9458b. |
| 3378 | |
| 3379 | If you can do that, you can now recreate the missing object with |
| 3380 | |
| 3381 | ------------------------------------------------ |
| 3382 | $ git hash-object -w <recreated-file> |
| 3383 | ------------------------------------------------ |
| 3384 | |
| 3385 | and your repository is good again! |
| 3386 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 3387 | (Btw, you could have ignored the `fsck`, and started with doing a |
J. Bruce Fields | 1cdade2 | 2007-03-03 22:53:37 -0500 | [diff] [blame] | 3388 | |
| 3389 | ------------------------------------------------ |
| 3390 | $ git log --raw --all |
| 3391 | ------------------------------------------------ |
| 3392 | |
Ann T Ropea | f61d89e | 2017-12-03 22:27:38 +0100 | [diff] [blame] | 3393 | and just looked for the sha of the missing object (4b9458b) in that |
W. Trevor King | da2c7b3 | 2013-02-10 10:10:39 -0500 | [diff] [blame] | 3394 | whole thing. It's up to you--Git does *have* a lot of information, it is |
J. Bruce Fields | 1cdade2 | 2007-03-03 22:53:37 -0500 | [diff] [blame] | 3395 | just missing one particular blob version. |
| 3396 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 3397 | [[the-index]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 3398 | === The index |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3399 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 3400 | The index is a binary file (generally kept in `.git/index`) containing a |
Felipe Contreras | a6e5ef7 | 2009-04-04 12:38:27 +0300 | [diff] [blame] | 3401 | sorted list of path names, each with permissions and the SHA-1 of a blob |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 3402 | object; linkgit:git-ls-files[1] can show you the contents of the index: |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3403 | |
J. Bruce Fields | 1c09789 | 2007-09-03 12:59:55 -0400 | [diff] [blame] | 3404 | ------------------------------------------------- |
| 3405 | $ git ls-files --stage |
| 3406 | 100644 63c918c667fa005ff12ad89437f2fdc80926e21c 0 .gitignore |
| 3407 | 100644 5529b198e8d14decbe4ad99db3f7fb632de0439d 0 .mailmap |
| 3408 | 100644 6ff87c4664981e4397625791c8ea3bbb5f2279a3 0 COPYING |
| 3409 | 100644 a37b2152bd26be2c2289e1f57a292534a51a93c7 0 Documentation/.gitignore |
| 3410 | 100644 fbefe9a45b00a54b58d94d06eca48b03d40a50e0 0 Documentation/Makefile |
| 3411 | ... |
| 3412 | 100644 2511aef8d89ab52be5ec6a5e46236b4b6bcd07ea 0 xdiff/xtypes.h |
| 3413 | 100644 2ade97b2574a9f77e7ae4002a4e07a6a38e46d07 0 xdiff/xutils.c |
| 3414 | 100644 d5de8292e05e7c36c4b68857c1cf9855e3d2f70a 0 xdiff/xutils.h |
| 3415 | ------------------------------------------------- |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3416 | |
J. Bruce Fields | 1c09789 | 2007-09-03 12:59:55 -0400 | [diff] [blame] | 3417 | Note that in older documentation you may see the index called the |
| 3418 | "current directory cache" or just the "cache". It has three important |
| 3419 | properties: |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3420 | |
J. Bruce Fields | 1c09789 | 2007-09-03 12:59:55 -0400 | [diff] [blame] | 3421 | 1. The index contains all the information necessary to generate a single |
| 3422 | (uniquely determined) tree object. |
| 3423 | + |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 3424 | For example, running linkgit:git-commit[1] generates this tree object |
J. Bruce Fields | 1c09789 | 2007-09-03 12:59:55 -0400 | [diff] [blame] | 3425 | from the index, stores it in the object database, and uses it as the |
| 3426 | tree object associated with the new commit. |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3427 | |
J. Bruce Fields | 1c09789 | 2007-09-03 12:59:55 -0400 | [diff] [blame] | 3428 | 2. The index enables fast comparisons between the tree object it defines |
| 3429 | and the working tree. |
| 3430 | + |
| 3431 | It does this by storing some additional data for each entry (such as |
| 3432 | the last modified time). This data is not displayed above, and is not |
| 3433 | stored in the created tree object, but it can be used to determine |
| 3434 | quickly which files in the working directory differ from what was |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 3435 | stored in the index, and thus save Git from having to read all of the |
J. Bruce Fields | 1c09789 | 2007-09-03 12:59:55 -0400 | [diff] [blame] | 3436 | data from such files to look for changes. |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3437 | |
J. Bruce Fields | 1c09789 | 2007-09-03 12:59:55 -0400 | [diff] [blame] | 3438 | 3. It can efficiently represent information about merge conflicts |
| 3439 | between different tree objects, allowing each pathname to be |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3440 | associated with sufficient information about the trees involved that |
J. Bruce Fields | 1c09789 | 2007-09-03 12:59:55 -0400 | [diff] [blame] | 3441 | you can create a three-way merge between them. |
| 3442 | + |
| 3443 | We saw in <<conflict-resolution>> that during a merge the index can |
| 3444 | store multiple versions of a single file (called "stages"). The third |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 3445 | column in the linkgit:git-ls-files[1] output above is the stage |
J. Bruce Fields | 1c09789 | 2007-09-03 12:59:55 -0400 | [diff] [blame] | 3446 | number, and will take on values other than 0 for files with merge |
| 3447 | conflicts. |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3448 | |
J. Bruce Fields | 1c09789 | 2007-09-03 12:59:55 -0400 | [diff] [blame] | 3449 | The index is thus a sort of temporary staging area, which is filled with |
| 3450 | a tree which you are in the process of working on. |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3451 | |
J. Bruce Fields | 1c09789 | 2007-09-03 12:59:55 -0400 | [diff] [blame] | 3452 | If you blow the index away entirely, you generally haven't lost any |
| 3453 | information as long as you have the name of the tree that it described. |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3454 | |
Miklos Vajna | 38a457b | 2007-09-20 02:34:14 +0200 | [diff] [blame] | 3455 | [[submodules]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 3456 | == Submodules |
Miklos Vajna | 38a457b | 2007-09-20 02:34:14 +0200 | [diff] [blame] | 3457 | |
Michael Smith | 6dd1436 | 2007-09-25 08:44:38 -0400 | [diff] [blame] | 3458 | Large projects are often composed of smaller, self-contained modules. For |
| 3459 | example, an embedded Linux distribution's source tree would include every |
| 3460 | piece of software in the distribution with some local modifications; a movie |
| 3461 | player might need to build against a specific, known-working version of a |
| 3462 | decompression library; several independent programs might all share the same |
| 3463 | build scripts. |
Miklos Vajna | 38a457b | 2007-09-20 02:34:14 +0200 | [diff] [blame] | 3464 | |
Michael Smith | 6dd1436 | 2007-09-25 08:44:38 -0400 | [diff] [blame] | 3465 | With centralized revision control systems this is often accomplished by |
| 3466 | including every module in one single repository. Developers can check out |
| 3467 | all modules or only the modules they need to work with. They can even modify |
| 3468 | files across several modules in a single commit while moving things around |
| 3469 | or updating APIs and translations. |
| 3470 | |
| 3471 | Git does not allow partial checkouts, so duplicating this approach in Git |
| 3472 | would force developers to keep a local copy of modules they are not |
| 3473 | interested in touching. Commits in an enormous checkout would be slower |
| 3474 | than you'd expect as Git would have to scan every directory for changes. |
| 3475 | If modules have a lot of local history, clones would take forever. |
| 3476 | |
| 3477 | On the plus side, distributed revision control systems can much better |
| 3478 | integrate with external sources. In a centralized model, a single arbitrary |
| 3479 | snapshot of the external project is exported from its own revision control |
| 3480 | and then imported into the local revision control on a vendor branch. All |
| 3481 | the history is hidden. With distributed revision control you can clone the |
| 3482 | entire external history and much more easily follow development and re-merge |
| 3483 | local changes. |
| 3484 | |
| 3485 | Git's submodule support allows a repository to contain, as a subdirectory, a |
| 3486 | checkout of an external project. Submodules maintain their own identity; |
| 3487 | the submodule support just stores the submodule repository location and |
| 3488 | commit ID, so other developers who clone the containing project |
| 3489 | ("superproject") can easily clone all the submodules at the same revision. |
| 3490 | Partial checkouts of the superproject are possible: you can tell Git to |
| 3491 | clone none, some or all of the submodules. |
| 3492 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 3493 | The linkgit:git-submodule[1] command is available since Git 1.5.3. Users |
Michael Smith | 6dd1436 | 2007-09-25 08:44:38 -0400 | [diff] [blame] | 3494 | with Git 1.5.2 can look up the submodule commits in the repository and |
| 3495 | manually check them out; earlier versions won't recognize the submodules at |
| 3496 | all. |
Miklos Vajna | 38a457b | 2007-09-20 02:34:14 +0200 | [diff] [blame] | 3497 | |
Thomas Ackermann | ddd4dde | 2013-08-27 19:59:21 +0200 | [diff] [blame] | 3498 | To see how submodule support works, create four example |
Miklos Vajna | 38a457b | 2007-09-20 02:34:14 +0200 | [diff] [blame] | 3499 | repositories that can be used later as a submodule: |
| 3500 | |
| 3501 | ------------------------------------------------- |
| 3502 | $ mkdir ~/git |
| 3503 | $ cd ~/git |
| 3504 | $ for i in a b c d |
| 3505 | do |
| 3506 | mkdir $i |
| 3507 | cd $i |
| 3508 | git init |
| 3509 | echo "module $i" > $i.txt |
| 3510 | git add $i.txt |
| 3511 | git commit -m "Initial commit, submodule $i" |
| 3512 | cd .. |
| 3513 | done |
| 3514 | ------------------------------------------------- |
| 3515 | |
| 3516 | Now create the superproject and add all the submodules: |
| 3517 | |
| 3518 | ------------------------------------------------- |
| 3519 | $ mkdir super |
| 3520 | $ cd super |
| 3521 | $ git init |
| 3522 | $ for i in a b c d |
| 3523 | do |
Abhijit Menon-Sen | a56bf58 | 2008-07-30 01:23:16 +0530 | [diff] [blame] | 3524 | git submodule add ~/git/$i $i |
Miklos Vajna | 38a457b | 2007-09-20 02:34:14 +0200 | [diff] [blame] | 3525 | done |
| 3526 | ------------------------------------------------- |
| 3527 | |
| 3528 | NOTE: Do not use local URLs here if you plan to publish your superproject! |
| 3529 | |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 3530 | See what files `git submodule` created: |
Miklos Vajna | 38a457b | 2007-09-20 02:34:14 +0200 | [diff] [blame] | 3531 | |
| 3532 | ------------------------------------------------- |
| 3533 | $ ls -a |
| 3534 | . .. .git .gitmodules a b c d |
| 3535 | ------------------------------------------------- |
| 3536 | |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 3537 | The `git submodule add <repo> <path>` command does a couple of things: |
Miklos Vajna | 38a457b | 2007-09-20 02:34:14 +0200 | [diff] [blame] | 3538 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 3539 | - It clones the submodule from `<repo>` to the given `<path>` under the |
Abhijit Menon-Sen | a56bf58 | 2008-07-30 01:23:16 +0530 | [diff] [blame] | 3540 | current directory and by default checks out the master branch. |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 3541 | - It adds the submodule's clone path to the linkgit:gitmodules[5] file and |
Michael Smith | 6dd1436 | 2007-09-25 08:44:38 -0400 | [diff] [blame] | 3542 | adds this file to the index, ready to be committed. |
Miklos Vajna | 38a457b | 2007-09-20 02:34:14 +0200 | [diff] [blame] | 3543 | - It adds the submodule's current commit ID to the index, ready to be |
| 3544 | committed. |
| 3545 | |
| 3546 | Commit the superproject: |
| 3547 | |
| 3548 | ------------------------------------------------- |
| 3549 | $ git commit -m "Add submodules a, b, c and d." |
| 3550 | ------------------------------------------------- |
| 3551 | |
| 3552 | Now clone the superproject: |
| 3553 | |
| 3554 | ------------------------------------------------- |
| 3555 | $ cd .. |
| 3556 | $ git clone super cloned |
| 3557 | $ cd cloned |
| 3558 | ------------------------------------------------- |
| 3559 | |
| 3560 | The submodule directories are there, but they're empty: |
| 3561 | |
| 3562 | ------------------------------------------------- |
| 3563 | $ ls -a a |
| 3564 | . .. |
| 3565 | $ git submodule status |
| 3566 | -d266b9873ad50488163457f025db7cdd9683d88b a |
| 3567 | -e81d457da15309b4fef4249aba9b50187999670d b |
| 3568 | -c1536a972b9affea0f16e0680ba87332dc059146 c |
| 3569 | -d96249ff5d57de5de093e6baff9e0aafa5276a74 d |
| 3570 | ------------------------------------------------- |
| 3571 | |
| 3572 | NOTE: The commit object names shown above would be different for you, but they |
| 3573 | should match the HEAD commit object names of your repositories. You can check |
| 3574 | it by running `git ls-remote ../a`. |
| 3575 | |
| 3576 | Pulling down the submodules is a two-step process. First run `git submodule |
| 3577 | init` to add the submodule repository URLs to `.git/config`: |
| 3578 | |
| 3579 | ------------------------------------------------- |
| 3580 | $ git submodule init |
| 3581 | ------------------------------------------------- |
| 3582 | |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 3583 | Now use `git submodule update` to clone the repositories and check out the |
Miklos Vajna | 38a457b | 2007-09-20 02:34:14 +0200 | [diff] [blame] | 3584 | commits specified in the superproject: |
| 3585 | |
| 3586 | ------------------------------------------------- |
| 3587 | $ git submodule update |
| 3588 | $ cd a |
| 3589 | $ ls -a |
| 3590 | . .. .git a.txt |
| 3591 | ------------------------------------------------- |
| 3592 | |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 3593 | One major difference between `git submodule update` and `git submodule add` is |
| 3594 | that `git submodule update` checks out a specific commit, rather than the tip |
Miklos Vajna | 38a457b | 2007-09-20 02:34:14 +0200 | [diff] [blame] | 3595 | of a branch. It's like checking out a tag: the head is detached, so you're not |
| 3596 | working on a branch. |
| 3597 | |
| 3598 | ------------------------------------------------- |
| 3599 | $ git branch |
Thomas Ackermann | 95f9be5 | 2013-08-27 19:56:04 +0200 | [diff] [blame] | 3600 | * (detached from d266b98) |
Miklos Vajna | 38a457b | 2007-09-20 02:34:14 +0200 | [diff] [blame] | 3601 | master |
| 3602 | ------------------------------------------------- |
| 3603 | |
| 3604 | If you want to make a change within a submodule and you have a detached head, |
| 3605 | then you should create or checkout a branch, make your changes, publish the |
| 3606 | change within the submodule, and then update the superproject to reference the |
| 3607 | new commit: |
| 3608 | |
| 3609 | ------------------------------------------------- |
Nguyễn Thái Ngọc Duy | 328c6cb | 2019-03-29 17:39:19 +0700 | [diff] [blame] | 3610 | $ git switch master |
Miklos Vajna | 38a457b | 2007-09-20 02:34:14 +0200 | [diff] [blame] | 3611 | ------------------------------------------------- |
| 3612 | |
| 3613 | or |
| 3614 | |
| 3615 | ------------------------------------------------- |
Nguyễn Thái Ngọc Duy | 328c6cb | 2019-03-29 17:39:19 +0700 | [diff] [blame] | 3616 | $ git switch -c fix-up |
Miklos Vajna | 38a457b | 2007-09-20 02:34:14 +0200 | [diff] [blame] | 3617 | ------------------------------------------------- |
| 3618 | |
| 3619 | then |
| 3620 | |
| 3621 | ------------------------------------------------- |
| 3622 | $ echo "adding a line again" >> a.txt |
| 3623 | $ git commit -a -m "Updated the submodule from within the superproject." |
| 3624 | $ git push |
| 3625 | $ cd .. |
| 3626 | $ git diff |
| 3627 | diff --git a/a b/a |
| 3628 | index d266b98..261dfac 160000 |
| 3629 | --- a/a |
| 3630 | +++ b/a |
| 3631 | @@ -1 +1 @@ |
| 3632 | -Subproject commit d266b9873ad50488163457f025db7cdd9683d88b |
| 3633 | +Subproject commit 261dfac35cb99d380eb966e102c1197139f7fa24 |
| 3634 | $ git add a |
| 3635 | $ git commit -m "Updated submodule a." |
| 3636 | $ git push |
| 3637 | ------------------------------------------------- |
| 3638 | |
| 3639 | You have to run `git submodule update` after `git pull` if you want to update |
| 3640 | submodules, too. |
| 3641 | |
Martin Ågren | e79b345 | 2019-09-22 13:57:56 +0200 | [diff] [blame] | 3642 | [[pitfalls-with-submodules]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 3643 | === Pitfalls with submodules |
Miklos Vajna | 38a457b | 2007-09-20 02:34:14 +0200 | [diff] [blame] | 3644 | |
| 3645 | Always publish the submodule change before publishing the change to the |
| 3646 | superproject that references it. If you forget to publish the submodule change, |
| 3647 | others won't be able to clone the repository: |
| 3648 | |
| 3649 | ------------------------------------------------- |
| 3650 | $ cd ~/git/super/a |
| 3651 | $ echo i added another line to this file >> a.txt |
| 3652 | $ git commit -a -m "doing it wrong this time" |
| 3653 | $ cd .. |
| 3654 | $ git add a |
| 3655 | $ git commit -m "Updated submodule a again." |
| 3656 | $ git push |
| 3657 | $ cd ~/git/cloned |
| 3658 | $ git pull |
| 3659 | $ git submodule update |
| 3660 | error: pathspec '261dfac35cb99d380eb966e102c1197139f7fa24' did not match any file(s) known to git. |
| 3661 | Did you forget to 'git add'? |
| 3662 | Unable to checkout '261dfac35cb99d380eb966e102c1197139f7fa24' in submodule path 'a' |
| 3663 | ------------------------------------------------- |
| 3664 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 3665 | In older Git versions it could be easily forgotten to commit new or modified |
Jens Lehmann | 8d9e7d5 | 2010-02-01 19:09:39 +0100 | [diff] [blame] | 3666 | files in a submodule, which silently leads to similar problems as not pushing |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 3667 | the submodule changes. Starting with Git 1.7.0 both `git status` and `git diff` |
Jens Lehmann | 8d9e7d5 | 2010-02-01 19:09:39 +0100 | [diff] [blame] | 3668 | in the superproject show submodules as modified when they contain new or |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 3669 | modified files to protect against accidentally committing such a state. `git |
| 3670 | diff` will also add a `-dirty` to the work tree side when generating patch |
| 3671 | output or used with the `--submodule` option: |
Jens Lehmann | 8d9e7d5 | 2010-02-01 19:09:39 +0100 | [diff] [blame] | 3672 | |
| 3673 | ------------------------------------------------- |
| 3674 | $ git diff |
| 3675 | diff --git a/sub b/sub |
| 3676 | --- a/sub |
| 3677 | +++ b/sub |
| 3678 | @@ -1 +1 @@ |
| 3679 | -Subproject commit 3f356705649b5d566d97ff843cf193359229a453 |
| 3680 | +Subproject commit 3f356705649b5d566d97ff843cf193359229a453-dirty |
| 3681 | $ git diff --submodule |
| 3682 | Submodule sub 3f35670..3f35670-dirty: |
| 3683 | ------------------------------------------------- |
| 3684 | |
Miklos Vajna | 38a457b | 2007-09-20 02:34:14 +0200 | [diff] [blame] | 3685 | You also should not rewind branches in a submodule beyond commits that were |
| 3686 | ever recorded in any superproject. |
| 3687 | |
| 3688 | It's not safe to run `git submodule update` if you've made and committed |
| 3689 | changes within a submodule without checking out a branch first. They will be |
| 3690 | silently overwritten: |
| 3691 | |
| 3692 | ------------------------------------------------- |
| 3693 | $ cat a.txt |
| 3694 | module a |
| 3695 | $ echo line added from private2 >> a.txt |
| 3696 | $ git commit -a -m "line added inside private2" |
| 3697 | $ cd .. |
| 3698 | $ git submodule update |
| 3699 | Submodule path 'a': checked out 'd266b9873ad50488163457f025db7cdd9683d88b' |
| 3700 | $ cd a |
| 3701 | $ cat a.txt |
| 3702 | module a |
| 3703 | ------------------------------------------------- |
| 3704 | |
| 3705 | NOTE: The changes are still visible in the submodule's reflog. |
| 3706 | |
W. Trevor King | 9148673 | 2013-02-19 05:05:02 -0500 | [diff] [blame] | 3707 | If you have uncommitted changes in your submodule working tree, `git |
| 3708 | submodule update` will not overwrite them. Instead, you get the usual |
| 3709 | warning about not being able switch from a dirty branch. |
Miklos Vajna | 38a457b | 2007-09-20 02:34:14 +0200 | [diff] [blame] | 3710 | |
J. Bruce Fields | 1c6045f | 2007-09-03 11:27:56 -0400 | [diff] [blame] | 3711 | [[low-level-operations]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 3712 | == Low-level Git operations |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3713 | |
J. Bruce Fields | 1c6045f | 2007-09-03 11:27:56 -0400 | [diff] [blame] | 3714 | Many of the higher-level commands were originally implemented as shell |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 3715 | scripts using a smaller core of low-level Git commands. These can still |
| 3716 | be useful when doing unusual things with Git, or just as a way to |
J. Bruce Fields | 1c6045f | 2007-09-03 11:27:56 -0400 | [diff] [blame] | 3717 | understand its inner workings. |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3718 | |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 3719 | [[object-manipulation]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 3720 | === Object access and manipulation |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 3721 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 3722 | The linkgit:git-cat-file[1] command can show the contents of any object, |
| 3723 | though the higher-level linkgit:git-show[1] is usually more useful. |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 3724 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 3725 | The linkgit:git-commit-tree[1] command allows constructing commits with |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 3726 | arbitrary parents and trees. |
| 3727 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 3728 | A tree can be created with linkgit:git-write-tree[1] and its data can be |
| 3729 | accessed by linkgit:git-ls-tree[1]. Two trees can be compared with |
| 3730 | linkgit:git-diff-tree[1]. |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 3731 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 3732 | A tag is created with linkgit:git-mktag[1], and the signature can be |
| 3733 | verified by linkgit:git-verify-tag[1], though it is normally simpler to |
| 3734 | use linkgit:git-tag[1] for both. |
J. Bruce Fields | 1bbf1c7 | 2007-06-10 15:15:08 -0400 | [diff] [blame] | 3735 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 3736 | [[the-workflow]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 3737 | === The Workflow |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3738 | |
Nguyễn Thái Ngọc Duy | 80f537f | 2019-04-25 16:45:58 +0700 | [diff] [blame] | 3739 | High-level operations such as linkgit:git-commit[1] and |
| 3740 | linkgit:git-restore[1] work by moving data |
Ralf Wildenhues | 06ada15 | 2007-10-09 23:00:03 +0200 | [diff] [blame] | 3741 | between the working tree, the index, and the object database. Git |
| 3742 | provides low-level operations which perform each of these steps |
| 3743 | individually. |
J. Bruce Fields | 1c6045f | 2007-09-03 11:27:56 -0400 | [diff] [blame] | 3744 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 3745 | Generally, all Git operations work on the index file. Some operations |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3746 | work *purely* on the index file (showing the current state of the |
J. Bruce Fields | 1c6045f | 2007-09-03 11:27:56 -0400 | [diff] [blame] | 3747 | index), but most operations move data between the index file and either |
| 3748 | the database or the working directory. Thus there are four main |
| 3749 | combinations: |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3750 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 3751 | [[working-directory-to-index]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 3752 | ==== working directory -> index |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3753 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 3754 | The linkgit:git-update-index[1] command updates the index with |
J. Bruce Fields | 1c6045f | 2007-09-03 11:27:56 -0400 | [diff] [blame] | 3755 | information from the working directory. You generally update the |
| 3756 | index information by just specifying the filename you want to update, |
| 3757 | like so: |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3758 | |
| 3759 | ------------------------------------------------- |
J. Bruce Fields | 1c6045f | 2007-09-03 11:27:56 -0400 | [diff] [blame] | 3760 | $ git update-index filename |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3761 | ------------------------------------------------- |
| 3762 | |
Øystein Walle | 5fe8f49 | 2014-02-05 23:19:43 +0100 | [diff] [blame] | 3763 | but to avoid common mistakes with filename globbing etc., the command |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3764 | will not normally add totally new entries or remove old entries, |
| 3765 | i.e. it will normally just update existing cache entries. |
| 3766 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 3767 | To tell Git that yes, you really do realize that certain files no |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3768 | longer exist, or that new files should be added, you |
| 3769 | should use the `--remove` and `--add` flags respectively. |
| 3770 | |
| 3771 | NOTE! A `--remove` flag does 'not' mean that subsequent filenames will |
| 3772 | necessarily be removed: if the files still exist in your directory |
| 3773 | structure, the index will be updated with their new status, not |
Johannes Schindelin | 10455d2 | 2007-11-30 11:35:23 +0000 | [diff] [blame] | 3774 | removed. The only thing `--remove` means is that update-index will be |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3775 | considering a removed file to be a valid thing, and if the file really |
| 3776 | does not exist any more, it will update the index accordingly. |
| 3777 | |
Jonathan Nieder | 467c019 | 2008-07-03 00:28:15 -0500 | [diff] [blame] | 3778 | As a special case, you can also do `git update-index --refresh`, which |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3779 | will refresh the "stat" information of each index to match the current |
| 3780 | stat information. It will 'not' update the object status itself, and |
| 3781 | it will only update the fields that are used to quickly test whether |
| 3782 | an object still matches its old backing store object. |
| 3783 | |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 3784 | The previously introduced linkgit:git-add[1] is just a wrapper for |
| 3785 | linkgit:git-update-index[1]. |
J. Bruce Fields | 1c6045f | 2007-09-03 11:27:56 -0400 | [diff] [blame] | 3786 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 3787 | [[index-to-object-database]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 3788 | ==== index -> object database |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3789 | |
| 3790 | You write your current index file to a "tree" object with the program |
| 3791 | |
| 3792 | ------------------------------------------------- |
J. Bruce Fields | 1c6045f | 2007-09-03 11:27:56 -0400 | [diff] [blame] | 3793 | $ git write-tree |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3794 | ------------------------------------------------- |
| 3795 | |
Ralf Wildenhues | 2ef8ac1 | 2007-10-09 23:05:30 +0200 | [diff] [blame] | 3796 | that doesn't come with any options--it will just write out the |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3797 | current index into the set of tree objects that describe that state, |
| 3798 | and it will return the name of the resulting top-level tree. You can |
| 3799 | use that tree to re-generate the index at any time by going in the |
| 3800 | other direction: |
| 3801 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 3802 | [[object-database-to-index]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 3803 | ==== object database -> index |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3804 | |
| 3805 | You read a "tree" file from the object database, and use that to |
Ralf Wildenhues | 2ef8ac1 | 2007-10-09 23:05:30 +0200 | [diff] [blame] | 3806 | populate (and overwrite--don't do this if your index contains any |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3807 | unsaved state that you might want to restore later!) your current |
| 3808 | index. Normal operation is just |
| 3809 | |
| 3810 | ------------------------------------------------- |
Felipe Contreras | a6e5ef7 | 2009-04-04 12:38:27 +0300 | [diff] [blame] | 3811 | $ git read-tree <SHA-1 of tree> |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3812 | ------------------------------------------------- |
| 3813 | |
| 3814 | and your index file will now be equivalent to the tree that you saved |
| 3815 | earlier. However, that is only your 'index' file: your working |
| 3816 | directory contents have not been modified. |
| 3817 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 3818 | [[index-to-working-directory]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 3819 | ==== index -> working directory |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3820 | |
| 3821 | You update your working directory from the index by "checking out" |
| 3822 | files. This is not a very common operation, since normally you'd just |
| 3823 | keep your files updated, and rather than write to your working |
| 3824 | directory, you'd tell the index files about the changes in your |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 3825 | working directory (i.e. `git update-index`). |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3826 | |
| 3827 | However, if you decide to jump to a new version, or check out somebody |
| 3828 | else's version, or just restore a previous tree, you'd populate your |
| 3829 | index file with read-tree, and then you need to check out the result |
| 3830 | with |
| 3831 | |
| 3832 | ------------------------------------------------- |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 3833 | $ git checkout-index filename |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3834 | ------------------------------------------------- |
| 3835 | |
| 3836 | or, if you want to check out all of the index, use `-a`. |
| 3837 | |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 3838 | NOTE! `git checkout-index` normally refuses to overwrite old files, so |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3839 | if you have an old version of the tree already checked out, you will |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 3840 | need to use the `-f` flag ('before' the `-a` flag or the filename) to |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3841 | 'force' the checkout. |
| 3842 | |
| 3843 | |
| 3844 | Finally, there are a few odds and ends which are not purely moving |
| 3845 | from one representation to the other: |
| 3846 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 3847 | [[tying-it-all-together]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 3848 | ==== Tying it all together |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3849 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 3850 | To commit a tree you have instantiated with `git write-tree`, you'd |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3851 | create a "commit" object that refers to that tree and the history |
Ralf Wildenhues | 2ef8ac1 | 2007-10-09 23:05:30 +0200 | [diff] [blame] | 3852 | behind it--most notably the "parent" commits that preceded it in |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3853 | history. |
| 3854 | |
| 3855 | Normally a "commit" has one parent: the previous state of the tree |
| 3856 | before a certain change was made. However, sometimes it can have two |
| 3857 | or more parent commits, in which case we call it a "merge", due to the |
| 3858 | fact that such a commit brings together ("merges") two or more |
| 3859 | previous states represented by other commits. |
| 3860 | |
| 3861 | In other words, while a "tree" represents a particular directory state |
Thomas Ackermann | ddd4dde | 2013-08-27 19:59:21 +0200 | [diff] [blame] | 3862 | of a working directory, a "commit" represents that state in time, |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3863 | and explains how we got there. |
| 3864 | |
| 3865 | You create a commit object by giving it the tree that describes the |
| 3866 | state at the time of the commit, and a list of parents: |
| 3867 | |
| 3868 | ------------------------------------------------- |
Štěpán Němec | 0adda93 | 2010-10-08 19:31:17 +0200 | [diff] [blame] | 3869 | $ git commit-tree <tree> -p <parent> [(-p <parent2>)...] |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3870 | ------------------------------------------------- |
| 3871 | |
| 3872 | and then giving the reason for the commit on stdin (either through |
| 3873 | redirection from a pipe or file, or by just typing it at the tty). |
| 3874 | |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 3875 | `git commit-tree` will return the name of the object that represents |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3876 | that commit, and you should save it away for later use. Normally, |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 3877 | you'd commit a new `HEAD` state, and while Git doesn't care where you |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3878 | save the note about that state, in practice we tend to just write the |
| 3879 | result to the file pointed at by `.git/HEAD`, so that we can always see |
| 3880 | what the last committed state was. |
| 3881 | |
Thomas Ackermann | 381183f | 2013-08-27 20:04:58 +0200 | [diff] [blame] | 3882 | Here is a picture that illustrates how various pieces fit together: |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3883 | |
| 3884 | ------------ |
| 3885 | |
| 3886 | commit-tree |
| 3887 | commit obj |
| 3888 | +----+ |
| 3889 | | | |
| 3890 | | | |
| 3891 | V V |
| 3892 | +-----------+ |
| 3893 | | Object DB | |
| 3894 | | Backing | |
| 3895 | | Store | |
| 3896 | +-----------+ |
| 3897 | ^ |
| 3898 | write-tree | | |
| 3899 | tree obj | | |
| 3900 | | | read-tree |
| 3901 | | | tree obj |
| 3902 | V |
| 3903 | +-----------+ |
| 3904 | | Index | |
| 3905 | | "cache" | |
| 3906 | +-----------+ |
| 3907 | update-index ^ |
| 3908 | blob obj | | |
| 3909 | | | |
| 3910 | checkout-index -u | | checkout-index |
| 3911 | stat | | blob obj |
| 3912 | V |
| 3913 | +-----------+ |
| 3914 | | Working | |
| 3915 | | Directory | |
| 3916 | +-----------+ |
| 3917 | |
| 3918 | ------------ |
| 3919 | |
| 3920 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 3921 | [[examining-the-data]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 3922 | === Examining the data |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3923 | |
| 3924 | You can examine the data represented in the object database and the |
| 3925 | index with various helper tools. For every object, you can use |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 3926 | linkgit:git-cat-file[1] to examine details about the |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3927 | object: |
| 3928 | |
| 3929 | ------------------------------------------------- |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 3930 | $ git cat-file -t <objectname> |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3931 | ------------------------------------------------- |
| 3932 | |
| 3933 | shows the type of the object, and once you have the type (which is |
| 3934 | usually implicit in where you find the object), you can use |
| 3935 | |
| 3936 | ------------------------------------------------- |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 3937 | $ git cat-file blob|tree|commit|tag <objectname> |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3938 | ------------------------------------------------- |
| 3939 | |
| 3940 | to show its contents. NOTE! Trees have binary content, and as a result |
| 3941 | there is a special helper for showing that content, called |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 3942 | `git ls-tree`, which turns the binary content into a more easily |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3943 | readable form. |
| 3944 | |
| 3945 | It's especially instructive to look at "commit" objects, since those |
| 3946 | tend to be small and fairly self-explanatory. In particular, if you |
| 3947 | follow the convention of having the top commit name in `.git/HEAD`, |
| 3948 | you can do |
| 3949 | |
| 3950 | ------------------------------------------------- |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 3951 | $ git cat-file commit HEAD |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3952 | ------------------------------------------------- |
| 3953 | |
| 3954 | to see what the top commit was. |
| 3955 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 3956 | [[merging-multiple-trees]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 3957 | === Merging multiple trees |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 3958 | |
Thomas Ackermann | e8e9964 | 2013-08-27 20:03:09 +0200 | [diff] [blame] | 3959 | Git can help you perform a three-way merge, which can in turn be |
| 3960 | used for a many-way merge by repeating the merge procedure several |
| 3961 | times. The usual situation is that you only do one three-way merge |
| 3962 | (reconciling two lines of history) and commit the result, but if |
| 3963 | you like to, you can merge several branches in one go. |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3964 | |
Thomas Ackermann | e8e9964 | 2013-08-27 20:03:09 +0200 | [diff] [blame] | 3965 | To perform a three-way merge, you start with the two commits you |
| 3966 | want to merge, find their closest common parent (a third commit), |
| 3967 | and compare the trees corresponding to these three commits. |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3968 | |
Thomas Ackermann | e8e9964 | 2013-08-27 20:03:09 +0200 | [diff] [blame] | 3969 | To get the "base" for the merge, look up the common parent of two |
| 3970 | commits: |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3971 | |
| 3972 | ------------------------------------------------- |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 3973 | $ git merge-base <commit1> <commit2> |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3974 | ------------------------------------------------- |
| 3975 | |
Thomas Ackermann | e8e9964 | 2013-08-27 20:03:09 +0200 | [diff] [blame] | 3976 | This prints the name of a commit they are both based on. You should |
| 3977 | now look up the tree objects of those commits, which you can easily |
| 3978 | do with |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3979 | |
| 3980 | ------------------------------------------------- |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 3981 | $ git cat-file commit <commitname> | head -1 |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3982 | ------------------------------------------------- |
| 3983 | |
| 3984 | since the tree object information is always the first line in a commit |
| 3985 | object. |
| 3986 | |
J. Bruce Fields | 1191ee1 | 2007-01-29 01:33:55 -0500 | [diff] [blame] | 3987 | Once you know the three trees you are going to merge (the one "original" |
J. Bruce Fields | c64415e | 2007-05-07 00:56:45 -0400 | [diff] [blame] | 3988 | tree, aka the common tree, and the two "result" trees, aka the branches |
J. Bruce Fields | 1191ee1 | 2007-01-29 01:33:55 -0500 | [diff] [blame] | 3989 | you want to merge), you do a "merge" read into the index. This will |
| 3990 | complain if it has to throw away your old index contents, so you should |
Ralf Wildenhues | 2ef8ac1 | 2007-10-09 23:05:30 +0200 | [diff] [blame] | 3991 | make sure that you've committed those--in fact you would normally |
J. Bruce Fields | 1191ee1 | 2007-01-29 01:33:55 -0500 | [diff] [blame] | 3992 | always do a merge against your last commit (which should thus match what |
| 3993 | you have in your current index anyway). |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3994 | |
| 3995 | To do the merge, do |
| 3996 | |
| 3997 | ------------------------------------------------- |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 3998 | $ git read-tree -m -u <origtree> <yourtree> <targettree> |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 3999 | ------------------------------------------------- |
| 4000 | |
| 4001 | which will do all trivial merge operations for you directly in the |
| 4002 | index file, and you can just write the result out with |
Jonathan Nieder | 467c019 | 2008-07-03 00:28:15 -0500 | [diff] [blame] | 4003 | `git write-tree`. |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 4004 | |
| 4005 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 4006 | [[merging-multiple-trees-2]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 4007 | === Merging multiple trees, continued |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 4008 | |
| 4009 | Sadly, many merges aren't trivial. If there are files that have |
Ralf Wildenhues | 06ada15 | 2007-10-09 23:00:03 +0200 | [diff] [blame] | 4010 | been added, moved or removed, or if both branches have modified the |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 4011 | same file, you will be left with an index tree that contains "merge |
| 4012 | entries" in it. Such an index tree can 'NOT' be written out to a tree |
| 4013 | object, and you will have to resolve any such merge clashes using |
| 4014 | other tools before you can write out the result. |
| 4015 | |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 4016 | You can examine such index state with `git ls-files --unmerged` |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 4017 | command. An example: |
| 4018 | |
| 4019 | ------------------------------------------------ |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 4020 | $ git read-tree -m $orig HEAD $target |
| 4021 | $ git ls-files --unmerged |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 4022 | 100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello.c |
| 4023 | 100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello.c |
| 4024 | 100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello.c |
| 4025 | ------------------------------------------------ |
| 4026 | |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 4027 | Each line of the `git ls-files --unmerged` output begins with |
Felipe Contreras | a6e5ef7 | 2009-04-04 12:38:27 +0300 | [diff] [blame] | 4028 | the blob mode bits, blob SHA-1, 'stage number', and the |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 4029 | filename. The 'stage number' is Git's way to say which tree it |
Štěpán Němec | edfbbf7 | 2012-07-15 00:20:36 +0200 | [diff] [blame] | 4030 | came from: stage 1 corresponds to the `$orig` tree, stage 2 to |
| 4031 | the `HEAD` tree, and stage 3 to the `$target` tree. |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 4032 | |
| 4033 | Earlier we said that trivial merges are done inside |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 4034 | `git read-tree -m`. For example, if the file did not change |
Justin Lebar | a58088a | 2014-03-31 15:11:44 -0700 | [diff] [blame] | 4035 | from `$orig` to `HEAD` or `$target`, or if the file changed |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 4036 | from `$orig` to `HEAD` and `$orig` to `$target` the same way, |
| 4037 | obviously the final outcome is what is in `HEAD`. What the |
| 4038 | above example shows is that file `hello.c` was changed from |
| 4039 | `$orig` to `HEAD` and `$orig` to `$target` in a different way. |
| 4040 | You could resolve this by running your favorite 3-way merge |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 4041 | program, e.g. `diff3`, `merge`, or Git's own merge-file, on |
J. Bruce Fields | c64415e | 2007-05-07 00:56:45 -0400 | [diff] [blame] | 4042 | the blob objects from these three stages yourself, like this: |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 4043 | |
| 4044 | ------------------------------------------------ |
Ann T Ropea | f61d89e | 2017-12-03 22:27:38 +0100 | [diff] [blame] | 4045 | $ git cat-file blob 263414f >hello.c~1 |
| 4046 | $ git cat-file blob 06fa6a2 >hello.c~2 |
| 4047 | $ git cat-file blob cc44c73 >hello.c~3 |
J. Bruce Fields | c64415e | 2007-05-07 00:56:45 -0400 | [diff] [blame] | 4048 | $ git merge-file hello.c~2 hello.c~1 hello.c~3 |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 4049 | ------------------------------------------------ |
| 4050 | |
| 4051 | This would leave the merge result in `hello.c~2` file, along |
| 4052 | with conflict markers if there are conflicts. After verifying |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 4053 | the merge result makes sense, you can tell Git what the final |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 4054 | merge result for this file is by: |
| 4055 | |
| 4056 | ------------------------------------------------- |
| 4057 | $ mv -f hello.c~2 hello.c |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 4058 | $ git update-index hello.c |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 4059 | ------------------------------------------------- |
| 4060 | |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 4061 | When a path is in the "unmerged" state, running `git update-index` for |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 4062 | that path tells Git to mark the path resolved. |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 4063 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 4064 | The above is the description of a Git merge at the lowest level, |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 4065 | to help you understand what conceptually happens under the hood. |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 4066 | In practice, nobody, not even Git itself, runs `git cat-file` three times |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 4067 | for this. There is a `git merge-index` program that extracts the |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 4068 | stages to temporary files and calls a "merge" script on it: |
| 4069 | |
| 4070 | ------------------------------------------------- |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 4071 | $ git merge-index git-merge-one-file hello.c |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 4072 | ------------------------------------------------- |
| 4073 | |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 4074 | and that is what higher level `git merge -s resolve` is implemented with. |
J. Bruce Fields | b181d57 | 2007-01-27 01:03:07 -0500 | [diff] [blame] | 4075 | |
J. Bruce Fields | 971aa71 | 2007-08-30 22:49:33 -0400 | [diff] [blame] | 4076 | [[hacking-git]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 4077 | == Hacking Git |
J. Bruce Fields | 971aa71 | 2007-08-30 22:49:33 -0400 | [diff] [blame] | 4078 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 4079 | This chapter covers internal details of the Git implementation which |
| 4080 | probably only Git developers need to understand. |
J. Bruce Fields | 971aa71 | 2007-08-30 22:49:33 -0400 | [diff] [blame] | 4081 | |
J. Bruce Fields | f2327c6 | 2007-08-30 23:07:05 -0400 | [diff] [blame] | 4082 | [[object-details]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 4083 | === Object storage format |
J. Bruce Fields | f2327c6 | 2007-08-30 23:07:05 -0400 | [diff] [blame] | 4084 | |
| 4085 | All objects have a statically determined "type" which identifies the |
| 4086 | format of the object (i.e. how it is used, and how it can refer to other |
| 4087 | objects). There are currently four different object types: "blob", |
| 4088 | "tree", "commit", and "tag". |
| 4089 | |
| 4090 | Regardless of object type, all objects share the following |
| 4091 | characteristics: they are all deflated with zlib, and have a header |
| 4092 | that not only specifies their type, but also provides size information |
Felipe Contreras | a6e5ef7 | 2009-04-04 12:38:27 +0300 | [diff] [blame] | 4093 | about the data in the object. It's worth noting that the SHA-1 hash |
J. Bruce Fields | f2327c6 | 2007-08-30 23:07:05 -0400 | [diff] [blame] | 4094 | that is used to name the object is the hash of the original data |
| 4095 | plus this header, so `sha1sum` 'file' does not match the object name |
Dirk Gouders | 28636d7 | 2024-03-12 11:41:56 +0100 | [diff] [blame] | 4096 | for 'file' (the earliest versions of Git hashed slightly differently |
| 4097 | but the conclusion is still the same). |
| 4098 | |
| 4099 | The following is a short example that demonstrates how these hashes |
| 4100 | can be generated manually: |
| 4101 | |
| 4102 | Let's assume a small text file with some simple content: |
| 4103 | |
| 4104 | ------------------------------------------------- |
| 4105 | $ echo "Hello world" >hello.txt |
| 4106 | ------------------------------------------------- |
| 4107 | |
| 4108 | We can now manually generate the hash Git would use for this file: |
| 4109 | |
| 4110 | - The object we want the hash for is of type "blob" and its size is |
| 4111 | 12 bytes. |
| 4112 | |
| 4113 | - Prepend the object header to the file content and feed this to |
| 4114 | `sha1sum`: |
| 4115 | |
| 4116 | ------------------------------------------------- |
| 4117 | $ { printf "blob 12\0"; cat hello.txt; } | sha1sum |
| 4118 | 802992c4220de19a90767f3000a79a31b98d0df7 - |
| 4119 | ------------------------------------------------- |
| 4120 | |
| 4121 | This manually constructed hash can be verified using `git hash-object` |
| 4122 | which of course hides the addition of the header: |
| 4123 | |
| 4124 | ------------------------------------------------- |
| 4125 | $ git hash-object hello.txt |
| 4126 | 802992c4220de19a90767f3000a79a31b98d0df7 |
| 4127 | ------------------------------------------------- |
J. Bruce Fields | f2327c6 | 2007-08-30 23:07:05 -0400 | [diff] [blame] | 4128 | |
| 4129 | As a result, the general consistency of an object can always be tested |
| 4130 | independently of the contents or the type of the object: all objects can |
| 4131 | be validated by verifying that (a) their hashes match the content of the |
| 4132 | file and (b) the object successfully inflates to a stream of bytes that |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 4133 | forms a sequence of |
Jean-Noël Avila | 2162f9f | 2023-12-25 21:21:26 +0000 | [diff] [blame] | 4134 | `<ascii-type-without-space> + <space> + <ascii-decimal-size> + |
| 4135 | <byte\0> + <binary-object-data>`. |
J. Bruce Fields | f2327c6 | 2007-08-30 23:07:05 -0400 | [diff] [blame] | 4136 | |
| 4137 | The structured objects can further have their structure and |
| 4138 | connectivity to other objects verified. This is generally done with |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 4139 | the `git fsck` program, which generates a full dependency graph |
J. Bruce Fields | f2327c6 | 2007-08-30 23:07:05 -0400 | [diff] [blame] | 4140 | of all objects, and verifies their internal consistency (in addition |
| 4141 | to just verifying their superficial consistency through the hash). |
| 4142 | |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4143 | [[birdview-on-the-source-code]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 4144 | === A birds-eye view of Git's source code |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4145 | |
J. Bruce Fields | a5fc33b | 2007-05-12 19:48:31 -0400 | [diff] [blame] | 4146 | It is not always easy for new developers to find their way through Git's |
| 4147 | source code. This section gives you a little guidance to show where to |
| 4148 | start. |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4149 | |
J. Bruce Fields | a5fc33b | 2007-05-12 19:48:31 -0400 | [diff] [blame] | 4150 | A good place to start is with the contents of the initial commit, with: |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4151 | |
| 4152 | ---------------------------------------------------- |
Nguyễn Thái Ngọc Duy | 328c6cb | 2019-03-29 17:39:19 +0700 | [diff] [blame] | 4153 | $ git switch --detach e83c5163 |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4154 | ---------------------------------------------------- |
| 4155 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 4156 | The initial revision lays the foundation for almost everything Git has |
Dirk Gouders | 28636d7 | 2024-03-12 11:41:56 +0100 | [diff] [blame] | 4157 | today (even though details may differ in a few places), but is small |
| 4158 | enough to read in one sitting. |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4159 | |
J. Bruce Fields | a5fc33b | 2007-05-12 19:48:31 -0400 | [diff] [blame] | 4160 | Note that terminology has changed since that revision. For example, the |
| 4161 | README in that revision uses the word "changeset" to describe what we |
| 4162 | now call a <<def_commit_object,commit>>. |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4163 | |
Elijah Newren | bc5c5ec | 2023-05-16 06:33:57 +0000 | [diff] [blame] | 4164 | Also, we do not call it "cache" any more, but rather "index"; however, |
| 4165 | the file is still called `read-cache.h`. |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4166 | |
J. Bruce Fields | a5fc33b | 2007-05-12 19:48:31 -0400 | [diff] [blame] | 4167 | If you grasp the ideas in that initial commit, you should check out a |
Elijah Newren | bc5c5ec | 2023-05-16 06:33:57 +0000 | [diff] [blame] | 4168 | more recent version and skim `read-cache-ll.h`, `object.h` and `commit.h`. |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4169 | |
| 4170 | In the early days, Git (in the tradition of UNIX) was a bunch of programs |
| 4171 | which were extremely simple, and which you used in scripts, piping the |
| 4172 | output of one into another. This turned out to be good for initial |
| 4173 | development, since it was easier to test new things. However, recently |
| 4174 | many of these parts have become builtins, and some of the core has been |
| 4175 | "libified", i.e. put into libgit.a for performance, portability reasons, |
| 4176 | and to avoid code duplication. |
| 4177 | |
| 4178 | By now, you know what the index is (and find the corresponding data |
Elijah Newren | bc5c5ec | 2023-05-16 06:33:57 +0000 | [diff] [blame] | 4179 | structures in `read-cache-ll.h`), and that there are just a couple of |
| 4180 | object types (blobs, trees, commits and tags) which inherit their |
| 4181 | common structure from `struct object`, which is their first member |
| 4182 | (and thus, you can cast e.g. `(struct object *)commit` to achieve the |
| 4183 | _same_ as `&commit->object`, i.e. get at the object name and flags). |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4184 | |
| 4185 | Now is a good point to take a break to let this information sink in. |
| 4186 | |
| 4187 | Next step: get familiar with the object naming. Read <<naming-commits>>. |
| 4188 | There are quite a few ways to name an object (and not only revisions!). |
| 4189 | All of these are handled in `sha1_name.c`. Just have a quick look at |
| 4190 | the function `get_sha1()`. A lot of the special handling is done by |
| 4191 | functions like `get_sha1_basic()` or the likes. |
| 4192 | |
| 4193 | This is just to get you into the groove for the most libified part of Git: |
| 4194 | the revision walker. |
| 4195 | |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 4196 | Basically, the initial version of `git log` was a shell script: |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4197 | |
| 4198 | ---------------------------------------------------------------- |
| 4199 | $ git-rev-list --pretty $(git-rev-parse --default HEAD "$@") | \ |
| 4200 | LESS=-S ${PAGER:-less} |
| 4201 | ---------------------------------------------------------------- |
| 4202 | |
| 4203 | What does this mean? |
| 4204 | |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 4205 | `git rev-list` is the original version of the revision walker, which |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4206 | _always_ printed a list of revisions to stdout. It is still functional, |
Ori Avtalion | 57f6ec0 | 2009-08-07 17:24:21 +0300 | [diff] [blame] | 4207 | and needs to, since most new Git commands start out as scripts using |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 4208 | `git rev-list`. |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4209 | |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 4210 | `git rev-parse` is not as important any more; it was only used to filter out |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4211 | options that were relevant for the different plumbing commands that were |
| 4212 | called by the script. |
| 4213 | |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 4214 | Most of what `git rev-list` did is contained in `revision.c` and |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4215 | `revision.h`. It wraps the options in a struct named `rev_info`, which |
| 4216 | controls how and what revisions are walked, and more. |
| 4217 | |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 4218 | The original job of `git rev-parse` is now taken by the function |
Jason St. John | 06ab60c | 2014-05-21 14:52:26 -0400 | [diff] [blame] | 4219 | `setup_revisions()`, which parses the revisions and the common command-line |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4220 | options for the revision walker. This information is stored in the struct |
Jason St. John | 06ab60c | 2014-05-21 14:52:26 -0400 | [diff] [blame] | 4221 | `rev_info` for later consumption. You can do your own command-line option |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4222 | parsing after calling `setup_revisions()`. After that, you have to call |
| 4223 | `prepare_revision_walk()` for initialization, and then you can get the |
| 4224 | commits one by one with the function `get_revision()`. |
| 4225 | |
| 4226 | If you are interested in more details of the revision walking process, |
| 4227 | just have a look at the first implementation of `cmd_log()`; call |
Jeff King | 6cf378f | 2012-04-26 04:51:57 -0400 | [diff] [blame] | 4228 | `git show v1.3.0~155^2~4` and scroll down to that function (note that you |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4229 | no longer need to call `setup_pager()` directly). |
| 4230 | |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 4231 | Nowadays, `git log` is a builtin, which means that it is _contained_ in the |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4232 | command `git`. The source side of a builtin is |
| 4233 | |
Phil Hord | 09b7e22 | 2013-06-18 13:44:58 -0400 | [diff] [blame] | 4234 | - a function called `cmd_<bla>`, typically defined in `builtin/<bla.c>` |
| 4235 | (note that older versions of Git used to have it in `builtin-<bla>.c` |
| 4236 | instead), and declared in `builtin.h`. |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4237 | |
| 4238 | - an entry in the `commands[]` array in `git.c`, and |
| 4239 | |
| 4240 | - an entry in `BUILTIN_OBJECTS` in the `Makefile`. |
| 4241 | |
| 4242 | Sometimes, more than one builtin is contained in one source file. For |
Phil Hord | 09b7e22 | 2013-06-18 13:44:58 -0400 | [diff] [blame] | 4243 | example, `cmd_whatchanged()` and `cmd_log()` both reside in `builtin/log.c`, |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4244 | since they share quite a bit of code. In that case, the commands which are |
| 4245 | _not_ named like the `.c` file in which they live have to be listed in |
| 4246 | `BUILT_INS` in the `Makefile`. |
| 4247 | |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 4248 | `git log` looks more complicated in C than it does in the original script, |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4249 | but that allows for a much greater flexibility and performance. |
| 4250 | |
| 4251 | Here again it is a good point to take a pause. |
| 4252 | |
| 4253 | Lesson three is: study the code. Really, it is the best way to learn about |
| 4254 | the organization of Git (after you know the basic concepts). |
| 4255 | |
| 4256 | So, think about something which you are interested in, say, "how can I |
| 4257 | access a blob just knowing the object name of it?". The first step is to |
| 4258 | find a Git command with which you can do it. In this example, it is either |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 4259 | `git show` or `git cat-file`. |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4260 | |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 4261 | For the sake of clarity, let's stay with `git cat-file`, because it |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4262 | |
| 4263 | - is plumbing, and |
| 4264 | |
| 4265 | - was around even in the initial commit (it literally went only through |
Phil Hord | 09b7e22 | 2013-06-18 13:44:58 -0400 | [diff] [blame] | 4266 | some 20 revisions as `cat-file.c`, was renamed to `builtin/cat-file.c` |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4267 | when made a builtin, and then saw less than 10 versions). |
| 4268 | |
Phil Hord | 09b7e22 | 2013-06-18 13:44:58 -0400 | [diff] [blame] | 4269 | So, look into `builtin/cat-file.c`, search for `cmd_cat_file()` and look what |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4270 | it does. |
| 4271 | |
| 4272 | ------------------------------------------------------------------ |
| 4273 | git_config(git_default_config); |
| 4274 | if (argc != 3) |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 4275 | usage("git cat-file [-t|-s|-e|-p|<type>] <sha1>"); |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4276 | if (get_sha1(argv[2], sha1)) |
| 4277 | die("Not a valid object name %s", argv[2]); |
| 4278 | ------------------------------------------------------------------ |
| 4279 | |
| 4280 | Let's skip over the obvious details; the only really interesting part |
| 4281 | here is the call to `get_sha1()`. It tries to interpret `argv[2]` as an |
| 4282 | object name, and if it refers to an object which is present in the current |
| 4283 | repository, it writes the resulting SHA-1 into the variable `sha1`. |
| 4284 | |
| 4285 | Two things are interesting here: |
| 4286 | |
| 4287 | - `get_sha1()` returns 0 on _success_. This might surprise some new |
| 4288 | Git hackers, but there is a long tradition in UNIX to return different |
Ralf Wildenhues | 2ef8ac1 | 2007-10-09 23:05:30 +0200 | [diff] [blame] | 4289 | negative numbers in case of different errors--and 0 on success. |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4290 | |
| 4291 | - the variable `sha1` in the function signature of `get_sha1()` is `unsigned |
Jeff King | 6cf378f | 2012-04-26 04:51:57 -0400 | [diff] [blame] | 4292 | char *`, but is actually expected to be a pointer to `unsigned |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4293 | char[20]`. This variable will contain the 160-bit SHA-1 of the given |
Jeff King | 6cf378f | 2012-04-26 04:51:57 -0400 | [diff] [blame] | 4294 | commit. Note that whenever a SHA-1 is passed as `unsigned char *`, it |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4295 | is the binary representation, as opposed to the ASCII representation in |
J. Bruce Fields | a5fc33b | 2007-05-12 19:48:31 -0400 | [diff] [blame] | 4296 | hex characters, which is passed as `char *`. |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4297 | |
| 4298 | You will see both of these things throughout the code. |
| 4299 | |
| 4300 | Now, for the meat: |
| 4301 | |
| 4302 | ----------------------------------------------------------------------------- |
| 4303 | case 0: |
| 4304 | buf = read_object_with_reference(sha1, argv[1], &size, NULL); |
| 4305 | ----------------------------------------------------------------------------- |
| 4306 | |
| 4307 | This is how you read a blob (actually, not only a blob, but any type of |
| 4308 | object). To know how the function `read_object_with_reference()` actually |
| 4309 | works, find the source code for it (something like `git grep |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 4310 | read_object_with | grep ":[a-z]"` in the Git repository), and read |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4311 | the source. |
| 4312 | |
| 4313 | To find out how the result can be used, just read on in `cmd_cat_file()`: |
| 4314 | |
| 4315 | ----------------------------------- |
| 4316 | write_or_die(1, buf, size); |
| 4317 | ----------------------------------- |
| 4318 | |
| 4319 | Sometimes, you do not know where to look for a feature. In many such cases, |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 4320 | it helps to search through the output of `git log`, and then `git show` the |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4321 | corresponding commit. |
| 4322 | |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 4323 | Example: If you know that there was some test case for `git bundle`, but |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4324 | do not remember where it was (yes, you _could_ `git grep bundle t/`, but that |
| 4325 | does not illustrate the point!): |
| 4326 | |
| 4327 | ------------------------ |
| 4328 | $ git log --no-merges t/ |
| 4329 | ------------------------ |
| 4330 | |
| 4331 | In the pager (`less`), just search for "bundle", go a few lines back, |
Ann T Ropea | f61d89e | 2017-12-03 22:27:38 +0100 | [diff] [blame] | 4332 | and see that it is in commit 18449ab0. Now just copy this object name, |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4333 | and paste it into the command line |
| 4334 | |
| 4335 | ------------------- |
| 4336 | $ git show 18449ab0 |
| 4337 | ------------------- |
| 4338 | |
| 4339 | Voila. |
| 4340 | |
| 4341 | Another example: Find out what to do in order to make some script a |
| 4342 | builtin: |
| 4343 | |
| 4344 | ------------------------------------------------- |
Phil Hord | 09b7e22 | 2013-06-18 13:44:58 -0400 | [diff] [blame] | 4345 | $ git log --no-merges --diff-filter=A builtin/*.c |
Johannes Schindelin | 126640a | 2007-05-10 12:36:15 +0200 | [diff] [blame] | 4346 | ------------------------------------------------- |
| 4347 | |
| 4348 | You see, Git is actually the best tool to find out about the source of Git |
| 4349 | itself! |
| 4350 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 4351 | [[glossary]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 4352 | == Git Glossary |
Christian Couder | 497c833 | 2008-05-29 19:21:46 +0200 | [diff] [blame] | 4353 | |
마누엘 | 03920ac | 2017-01-02 17:03:57 +0100 | [diff] [blame] | 4354 | [[git-explained]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 4355 | === Git explained |
마누엘 | 03920ac | 2017-01-02 17:03:57 +0100 | [diff] [blame] | 4356 | |
Christian Couder | 497c833 | 2008-05-29 19:21:46 +0200 | [diff] [blame] | 4357 | include::glossary-content.txt[] |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 4358 | |
J. Bruce Fields | 2624d9a | 2007-05-12 22:55:40 -0400 | [diff] [blame] | 4359 | [[git-quick-start]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 4360 | [appendix] |
| 4361 | == Git Quick Reference |
J. Bruce Fields | 2624d9a | 2007-05-12 22:55:40 -0400 | [diff] [blame] | 4362 | |
J. Bruce Fields | 99f171b | 2007-06-05 18:33:27 -0400 | [diff] [blame] | 4363 | This is a quick summary of the major commands; the previous chapters |
| 4364 | explain how these work in more detail. |
J. Bruce Fields | 2624d9a | 2007-05-12 22:55:40 -0400 | [diff] [blame] | 4365 | |
| 4366 | [[quick-creating-a-new-repository]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 4367 | === Creating a new repository |
J. Bruce Fields | 2624d9a | 2007-05-12 22:55:40 -0400 | [diff] [blame] | 4368 | |
| 4369 | From a tarball: |
| 4370 | |
| 4371 | ----------------------------------------------- |
| 4372 | $ tar xzf project.tar.gz |
| 4373 | $ cd project |
| 4374 | $ git init |
| 4375 | Initialized empty Git repository in .git/ |
| 4376 | $ git add . |
| 4377 | $ git commit |
| 4378 | ----------------------------------------------- |
| 4379 | |
| 4380 | From a remote repository: |
| 4381 | |
| 4382 | ----------------------------------------------- |
| 4383 | $ git clone git://example.com/pub/project.git |
| 4384 | $ cd project |
| 4385 | ----------------------------------------------- |
| 4386 | |
| 4387 | [[managing-branches]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 4388 | === Managing branches |
J. Bruce Fields | 2624d9a | 2007-05-12 22:55:40 -0400 | [diff] [blame] | 4389 | |
| 4390 | ----------------------------------------------- |
Nguyễn Thái Ngọc Duy | 328c6cb | 2019-03-29 17:39:19 +0700 | [diff] [blame] | 4391 | $ git branch # list all local branches in this repo |
| 4392 | $ git switch test # switch working directory to branch "test" |
| 4393 | $ git branch new # create branch "new" starting at current HEAD |
| 4394 | $ git branch -d new # delete branch "new" |
J. Bruce Fields | 2624d9a | 2007-05-12 22:55:40 -0400 | [diff] [blame] | 4395 | ----------------------------------------------- |
| 4396 | |
Ralf Wildenhues | 06ada15 | 2007-10-09 23:00:03 +0200 | [diff] [blame] | 4397 | Instead of basing a new branch on current HEAD (the default), use: |
J. Bruce Fields | 2624d9a | 2007-05-12 22:55:40 -0400 | [diff] [blame] | 4398 | |
| 4399 | ----------------------------------------------- |
| 4400 | $ git branch new test # branch named "test" |
| 4401 | $ git branch new v2.6.15 # tag named v2.6.15 |
| 4402 | $ git branch new HEAD^ # commit before the most recent |
| 4403 | $ git branch new HEAD^^ # commit before that |
| 4404 | $ git branch new test~10 # ten commits before tip of branch "test" |
| 4405 | ----------------------------------------------- |
| 4406 | |
| 4407 | Create and switch to a new branch at the same time: |
| 4408 | |
| 4409 | ----------------------------------------------- |
Nguyễn Thái Ngọc Duy | 328c6cb | 2019-03-29 17:39:19 +0700 | [diff] [blame] | 4410 | $ git switch -c new v2.6.15 |
J. Bruce Fields | 2624d9a | 2007-05-12 22:55:40 -0400 | [diff] [blame] | 4411 | ----------------------------------------------- |
| 4412 | |
| 4413 | Update and examine branches from the repository you cloned from: |
| 4414 | |
| 4415 | ----------------------------------------------- |
| 4416 | $ git fetch # update |
| 4417 | $ git branch -r # list |
| 4418 | origin/master |
| 4419 | origin/next |
| 4420 | ... |
Nguyễn Thái Ngọc Duy | 328c6cb | 2019-03-29 17:39:19 +0700 | [diff] [blame] | 4421 | $ git switch -c masterwork origin/master |
J. Bruce Fields | 2624d9a | 2007-05-12 22:55:40 -0400 | [diff] [blame] | 4422 | ----------------------------------------------- |
| 4423 | |
| 4424 | Fetch a branch from a different repository, and give it a new |
| 4425 | name in your repository: |
| 4426 | |
| 4427 | ----------------------------------------------- |
| 4428 | $ git fetch git://example.com/project.git theirbranch:mybranch |
| 4429 | $ git fetch git://example.com/project.git v2.6.15:mybranch |
| 4430 | ----------------------------------------------- |
| 4431 | |
| 4432 | Keep a list of repositories you work with regularly: |
| 4433 | |
| 4434 | ----------------------------------------------- |
| 4435 | $ git remote add example git://example.com/project.git |
| 4436 | $ git remote # list remote repositories |
| 4437 | example |
| 4438 | origin |
| 4439 | $ git remote show example # get details |
| 4440 | * remote example |
| 4441 | URL: git://example.com/project.git |
| 4442 | Tracked remote branches |
Johannes Sixt | 20244ea | 2008-10-22 09:39:47 +0200 | [diff] [blame] | 4443 | master |
| 4444 | next |
| 4445 | ... |
J. Bruce Fields | 2624d9a | 2007-05-12 22:55:40 -0400 | [diff] [blame] | 4446 | $ git fetch example # update branches from example |
| 4447 | $ git branch -r # list all remote branches |
| 4448 | ----------------------------------------------- |
| 4449 | |
| 4450 | |
| 4451 | [[exploring-history]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 4452 | === Exploring history |
J. Bruce Fields | 2624d9a | 2007-05-12 22:55:40 -0400 | [diff] [blame] | 4453 | |
| 4454 | ----------------------------------------------- |
| 4455 | $ gitk # visualize and browse history |
| 4456 | $ git log # list all commits |
| 4457 | $ git log src/ # ...modifying src/ |
| 4458 | $ git log v2.6.15..v2.6.16 # ...in v2.6.16, not in v2.6.15 |
| 4459 | $ git log master..test # ...in branch test, not in branch master |
| 4460 | $ git log test..master # ...in branch master, but not in test |
| 4461 | $ git log test...master # ...in one branch, not in both |
| 4462 | $ git log -S'foo()' # ...where difference contain "foo()" |
| 4463 | $ git log --since="2 weeks ago" |
| 4464 | $ git log -p # show patches as well |
| 4465 | $ git show # most recent commit |
| 4466 | $ git diff v2.6.15..v2.6.16 # diff between two tagged versions |
| 4467 | $ git diff v2.6.15..HEAD # diff with current head |
| 4468 | $ git grep "foo()" # search working directory for "foo()" |
| 4469 | $ git grep v2.6.15 "foo()" # search old tree for "foo()" |
| 4470 | $ git show v2.6.15:a.txt # look at old version of a.txt |
| 4471 | ----------------------------------------------- |
| 4472 | |
| 4473 | Search for regressions: |
| 4474 | |
| 4475 | ----------------------------------------------- |
| 4476 | $ git bisect start |
| 4477 | $ git bisect bad # current version is bad |
| 4478 | $ git bisect good v2.6.13-rc2 # last known good revision |
| 4479 | Bisecting: 675 revisions left to test after this |
| 4480 | # test here, then: |
| 4481 | $ git bisect good # if this revision is good, or |
| 4482 | $ git bisect bad # if this revision is bad. |
| 4483 | # repeat until done. |
| 4484 | ----------------------------------------------- |
| 4485 | |
| 4486 | [[making-changes]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 4487 | === Making changes |
J. Bruce Fields | 2624d9a | 2007-05-12 22:55:40 -0400 | [diff] [blame] | 4488 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 4489 | Make sure Git knows who to blame: |
J. Bruce Fields | 2624d9a | 2007-05-12 22:55:40 -0400 | [diff] [blame] | 4490 | |
| 4491 | ------------------------------------------------ |
| 4492 | $ cat >>~/.gitconfig <<\EOF |
| 4493 | [user] |
| 4494 | name = Your Name Comes Here |
| 4495 | email = you@yourdomain.example.com |
| 4496 | EOF |
| 4497 | ------------------------------------------------ |
| 4498 | |
| 4499 | Select file contents to include in the next commit, then make the |
| 4500 | commit: |
| 4501 | |
| 4502 | ----------------------------------------------- |
| 4503 | $ git add a.txt # updated file |
| 4504 | $ git add b.txt # new file |
| 4505 | $ git rm c.txt # old file |
| 4506 | $ git commit |
| 4507 | ----------------------------------------------- |
| 4508 | |
| 4509 | Or, prepare and create the commit in one step: |
| 4510 | |
| 4511 | ----------------------------------------------- |
| 4512 | $ git commit d.txt # use latest content only of d.txt |
| 4513 | $ git commit -a # use latest content of all tracked files |
| 4514 | ----------------------------------------------- |
| 4515 | |
| 4516 | [[merging]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 4517 | === Merging |
J. Bruce Fields | 2624d9a | 2007-05-12 22:55:40 -0400 | [diff] [blame] | 4518 | |
| 4519 | ----------------------------------------------- |
| 4520 | $ git merge test # merge branch "test" into the current branch |
| 4521 | $ git pull git://example.com/project.git master |
| 4522 | # fetch and merge in remote branch |
| 4523 | $ git pull . test # equivalent to git merge test |
| 4524 | ----------------------------------------------- |
| 4525 | |
| 4526 | [[sharing-your-changes]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 4527 | === Sharing your changes |
J. Bruce Fields | 2624d9a | 2007-05-12 22:55:40 -0400 | [diff] [blame] | 4528 | |
| 4529 | Importing or exporting patches: |
| 4530 | |
| 4531 | ----------------------------------------------- |
| 4532 | $ git format-patch origin..HEAD # format a patch for each commit |
| 4533 | # in HEAD but not in origin |
| 4534 | $ git am mbox # import patches from the mailbox "mbox" |
| 4535 | ----------------------------------------------- |
| 4536 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 4537 | Fetch a branch in a different Git repository, then merge into the |
J. Bruce Fields | 2624d9a | 2007-05-12 22:55:40 -0400 | [diff] [blame] | 4538 | current branch: |
| 4539 | |
| 4540 | ----------------------------------------------- |
| 4541 | $ git pull git://example.com/project.git theirbranch |
| 4542 | ----------------------------------------------- |
| 4543 | |
| 4544 | Store the fetched branch into a local branch before merging into the |
| 4545 | current branch: |
| 4546 | |
| 4547 | ----------------------------------------------- |
| 4548 | $ git pull git://example.com/project.git theirbranch:mybranch |
| 4549 | ----------------------------------------------- |
| 4550 | |
| 4551 | After creating commits on a local branch, update the remote |
| 4552 | branch with your commits: |
| 4553 | |
| 4554 | ----------------------------------------------- |
| 4555 | $ git push ssh://example.com/project.git mybranch:theirbranch |
| 4556 | ----------------------------------------------- |
| 4557 | |
| 4558 | When remote and local branch are both named "test": |
| 4559 | |
| 4560 | ----------------------------------------------- |
| 4561 | $ git push ssh://example.com/project.git test |
| 4562 | ----------------------------------------------- |
| 4563 | |
| 4564 | Shortcut version for a frequently used remote repository: |
| 4565 | |
| 4566 | ----------------------------------------------- |
| 4567 | $ git remote add example ssh://example.com/project.git |
| 4568 | $ git push example test |
| 4569 | ----------------------------------------------- |
| 4570 | |
| 4571 | [[repository-maintenance]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 4572 | === Repository maintenance |
J. Bruce Fields | 2624d9a | 2007-05-12 22:55:40 -0400 | [diff] [blame] | 4573 | |
| 4574 | Check for corruption: |
| 4575 | |
| 4576 | ----------------------------------------------- |
| 4577 | $ git fsck |
| 4578 | ----------------------------------------------- |
| 4579 | |
| 4580 | Recompress, remove unused cruft: |
| 4581 | |
| 4582 | ----------------------------------------------- |
| 4583 | $ git gc |
| 4584 | ----------------------------------------------- |
| 4585 | |
| 4586 | |
J. Bruce Fields | e34caac | 2007-04-18 00:46:19 -0400 | [diff] [blame] | 4587 | [[todo]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 4588 | [appendix] |
| 4589 | == Notes and todo list for this manual |
J. Bruce Fields | 6bd9b68 | 2007-01-07 22:58:14 -0500 | [diff] [blame] | 4590 | |
마누엘 | 03920ac | 2017-01-02 17:03:57 +0100 | [diff] [blame] | 4591 | [[todo-list]] |
Martin Ågren | fd5b820 | 2019-09-22 13:57:57 +0200 | [diff] [blame] | 4592 | === Todo list |
마누엘 | 03920ac | 2017-01-02 17:03:57 +0100 | [diff] [blame] | 4593 | |
J. Bruce Fields | 6bd9b68 | 2007-01-07 22:58:14 -0500 | [diff] [blame] | 4594 | This is a work in progress. |
| 4595 | |
| 4596 | The basic requirements: |
J. Bruce Fields | ecd95b5 | 2007-09-02 23:28:49 -0400 | [diff] [blame] | 4597 | |
| 4598 | - It must be readable in order, from beginning to end, by someone |
| 4599 | intelligent with a basic grasp of the UNIX command line, but without |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 4600 | any special knowledge of Git. If necessary, any other prerequisites |
J. Bruce Fields | ecd95b5 | 2007-09-02 23:28:49 -0400 | [diff] [blame] | 4601 | should be specifically mentioned as they arise. |
| 4602 | - Whenever possible, section headings should clearly describe the task |
| 4603 | they explain how to do, in language that requires no more knowledge |
| 4604 | than necessary: for example, "importing patches into a project" rather |
Felipe Contreras | 6127c08 | 2009-04-04 12:38:23 +0300 | [diff] [blame] | 4605 | than "the `git am` command" |
J. Bruce Fields | 6bd9b68 | 2007-01-07 22:58:14 -0500 | [diff] [blame] | 4606 | |
J. Bruce Fields | d5cd5de | 2007-01-09 00:18:09 -0500 | [diff] [blame] | 4607 | Think about how to create a clear chapter dependency graph that will |
| 4608 | allow people to get to important topics without necessarily reading |
| 4609 | everything in between. |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 4610 | |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 4611 | Scan `Documentation/` for other stuff left out; in particular: |
J. Bruce Fields | ecd95b5 | 2007-09-02 23:28:49 -0400 | [diff] [blame] | 4612 | |
| 4613 | - howto's |
W. Trevor King | 1249d8a | 2013-02-25 17:53:00 -0500 | [diff] [blame] | 4614 | - some of `technical/`? |
J. Bruce Fields | ecd95b5 | 2007-09-02 23:28:49 -0400 | [diff] [blame] | 4615 | - hooks |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 4616 | - list of commands in linkgit:git[1] |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 4617 | |
| 4618 | Scan email archives for other stuff left out |
| 4619 | |
| 4620 | Scan man pages to see if any assume more background than this manual |
| 4621 | provides. |
| 4622 | |
J. Bruce Fields | 2f99710 | 2007-01-14 22:43:47 -0500 | [diff] [blame] | 4623 | Add more good examples. Entire sections of just cookbook examples |
| 4624 | might be a good idea; maybe make an "advanced examples" section a |
| 4625 | standard end-of-chapter section? |
J. Bruce Fields | d19fbc3 | 2007-01-07 19:23:49 -0500 | [diff] [blame] | 4626 | |
| 4627 | Include cross-references to the glossary, where appropriate. |
| 4628 | |
Pavel Roskin | 3dff537 | 2007-02-03 23:49:16 -0500 | [diff] [blame] | 4629 | Add a section on working with other version control systems, including |
J. Bruce Fields | 9a24122 | 2007-01-29 01:43:33 -0500 | [diff] [blame] | 4630 | CVS, Subversion, and just imports of series of release tarballs. |
| 4631 | |
J. Bruce Fields | 0b375ab | 2007-01-30 12:48:48 -0500 | [diff] [blame] | 4632 | Write a chapter on using plumbing and writing scripts. |
J. Bruce Fields | d9bd321 | 2007-02-06 02:55:07 -0500 | [diff] [blame] | 4633 | |
| 4634 | Alternates, clone -reference, etc. |
| 4635 | |
J. Bruce Fields | 1cdade2 | 2007-03-03 22:53:37 -0500 | [diff] [blame] | 4636 | More on recovery from repository corruption. See: |
Denton Liu | dcee037 | 2019-12-02 11:26:18 -0800 | [diff] [blame] | 4637 | https://lore.kernel.org/git/Pine.LNX.4.64.0702272039540.12485@woody.linux-foundation.org/ |
| 4638 | https://lore.kernel.org/git/Pine.LNX.4.64.0702141033400.3604@woody.linux-foundation.org/ |