blob: 90a4189358300b0b594cdb18a90ce3b25d03de44 [file] [log] [blame]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02001= Git User Manual
J. Bruce Fields99eaefd2007-05-13 02:23:11 -04002
Firmin Martinfc12b6f2021-04-04 06:07:39 +02003[preface]
4== Introduction
5
J. Bruce Fields99eaefd2007-05-13 02:23:11 -04006Git is a fast distributed revision control system.
7
Brian Hetro02783072007-08-23 20:44:13 -04008This manual is designed to be readable by someone with basic UNIX
Thomas Ackermann2de9b712013-01-21 20:17:53 +01009command-line skills, but no previous knowledge of Git.
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -050010
J. Bruce Fields2624d9a2007-05-12 22:55:40 -040011<<repositories-and-branches>> and <<exploring-git-history>> explain how
12to fetch and study a project using git--read these chapters to learn how
13to build and test a particular version of a software project, search for
14regressions, and so on.
J. Bruce Fieldsef89f702007-01-20 21:41:48 -050015
J. Bruce Fields2624d9a2007-05-12 22:55:40 -040016People needing to do actual development will also want to read
Junio C Hamanoaa971cb2008-12-07 18:38:46 -080017<<Developing-With-git>> and <<sharing-development>>.
J. Bruce Fields6bd9b682007-01-07 22:58:14 -050018
19Further chapters cover more specialized topics.
20
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -050021Comprehensive reference documentation is available through the man
Christian Couderb3d98882008-11-17 16:42:47 +010022pages, or linkgit:git-help[1] command. For example, for the command
W. Trevor King1249d8a2013-02-25 17:53:00 -050023`git clone <repo>`, you can either use:
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -050024
25------------------------------------------------
26$ man git-clone
27------------------------------------------------
28
Christian Couderb3d98882008-11-17 16:42:47 +010029or:
30
31------------------------------------------------
32$ git help clone
33------------------------------------------------
34
35With the latter, you can use the manual viewer of your choice; see
36linkgit:git-help[1] for more information.
37
Thomas Ackermann2de9b712013-01-21 20:17:53 +010038See also <<git-quick-start>> for a brief overview of Git commands,
J. Bruce Fields2624d9a2007-05-12 22:55:40 -040039without any explanation.
J. Bruce Fieldsef89f702007-01-20 21:41:48 -050040
J. Bruce Fields99f171b2007-06-05 18:33:27 -040041Finally, see <<todo>> for ways that you can help make this manual more
J. Bruce Fields2624d9a2007-05-12 22:55:40 -040042complete.
J. Bruce Fieldsef89f702007-01-20 21:41:48 -050043
J. Bruce Fieldsb181d572007-01-27 01:03:07 -050044
J. Bruce Fieldse34caac2007-04-18 00:46:19 -040045[[repositories-and-branches]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +020046== Repositories and Branches
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -050047
J. Bruce Fieldse34caac2007-04-18 00:46:19 -040048[[how-to-get-a-git-repository]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +020049=== How to get a Git repository
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -050050
Thomas Ackermann2de9b712013-01-21 20:17:53 +010051It will be useful to have a Git repository to experiment with as you
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -050052read this manual.
53
Dan McGee5162e692007-12-29 00:20:38 -060054The best way to get one is by using the linkgit:git-clone[1] command to
J. Bruce Fieldsa5f90f32007-06-06 18:41:43 -040055download a copy of an existing repository. If you don't already have a
56project in mind, here are some interesting examples:
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -050057
58------------------------------------------------
W. Trevor King4b9ced22013-06-18 21:55:22 -040059 # Git itself (approx. 40MB download):
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -050060$ git clone git://git.kernel.org/pub/scm/git/git.git
W. Trevor King4b9ced22013-06-18 21:55:22 -040061 # the Linux kernel (approx. 640MB download):
62$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -050063------------------------------------------------
64
65The initial clone may be time-consuming for a large project, but you
66will only need to clone once.
67
W. Trevor King283efb02013-06-22 10:46:27 -040068The 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 Fieldsd19fbc32007-01-07 19:23:49 -050070directory, you will see that it contains a copy of the project files,
J. Bruce Fields0c4a33b2007-11-25 13:53:37 -050071called the <<def_working_tree,working tree>>, together with a special
W. Trevor King1249d8a2013-02-25 17:53:00 -050072top-level directory named `.git`, which contains all the information
J. Bruce Fields0c4a33b2007-11-25 13:53:37 -050073about the history of the project.
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -050074
J. Bruce Fieldse34caac2007-04-18 00:46:19 -040075[[how-to-check-out]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +020076=== How to check out a different version of a project
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -050077
J. Bruce Fieldsa2ef9d62007-08-18 22:16:24 -040078Git is best thought of as a tool for storing the history of a collection
79of files. It stores the history as a compressed collection of
Thomas Ackermann2de9b712013-01-21 20:17:53 +010080interrelated snapshots of the project's contents. In Git each such
J. Bruce Fieldsa2ef9d62007-08-18 22:16:24 -040081version is called a <<def_commit,commit>>.
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -050082
J. Bruce Fields0c4a33b2007-11-25 13:53:37 -050083Those snapshots aren't necessarily all arranged in a single line from
84oldest to newest; instead, work may simultaneously proceed along
Gustaf Hendeby57283292007-12-31 14:31:35 +010085parallel lines of development, called <<def_branch,branches>>, which may
J. Bruce Fields0c4a33b2007-11-25 13:53:37 -050086merge and diverge.
87
Thomas Ackermann2de9b712013-01-21 20:17:53 +010088A single Git repository can track development on multiple branches. It
J. Bruce Fields0c4a33b2007-11-25 13:53:37 -050089does this by keeping a list of <<def_head,heads>> which reference the
Dan McGee5162e692007-12-29 00:20:38 -060090latest commit on each branch; the linkgit:git-branch[1] command shows
J. Bruce Fields81b6c952007-03-18 23:02:14 -040091you the list of branch heads:
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -050092
93------------------------------------------------
94$ git branch
95* master
96------------------------------------------------
97
J. Bruce Fields4f752402007-04-16 00:37:13 -040098A freshly cloned repository contains a single branch head, by default
99named "master", with the working directory initialized to the state of
100the project referred to by that branch head.
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500101
J. Bruce Fields81b6c952007-03-18 23:02:14 -0400102Most projects also use <<def_tag,tags>>. Tags, like heads, are
103references into the project's history, and can be listed using the
Dan McGee5162e692007-12-29 00:20:38 -0600104linkgit:git-tag[1] command:
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500105
106------------------------------------------------
107$ git tag -l
108v2.6.11
109v2.6.11-tree
110v2.6.12
111v2.6.12-rc2
112v2.6.12-rc3
113v2.6.12-rc4
114v2.6.12-rc5
115v2.6.12-rc6
116v2.6.13
117...
118------------------------------------------------
119
J. Bruce Fieldsfe4b3e52007-01-21 22:14:39 -0500120Tags are expected to always point at the same version of a project,
J. Bruce Fields81b6c952007-03-18 23:02:14 -0400121while heads are expected to advance as development progresses.
J. Bruce Fieldsfe4b3e52007-01-21 22:14:39 -0500122
J. Bruce Fields81b6c952007-03-18 23:02:14 -0400123Create a new branch head pointing to one of these versions and check it
Nguyễn Thái Ngọc Duy328c6cb2019-03-29 17:39:19 +0700124out using linkgit:git-switch[1]:
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500125
126------------------------------------------------
Nguyễn Thái Ngọc Duy328c6cb2019-03-29 17:39:19 +0700127$ git switch -c new v2.6.13
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500128------------------------------------------------
129
130The working directory then reflects the contents that the project had
Dan McGee5162e692007-12-29 00:20:38 -0600131when it was tagged v2.6.13, and linkgit:git-branch[1] shows two
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500132branches, with an asterisk marking the currently checked-out branch:
133
134------------------------------------------------
135$ git branch
136 master
137* new
138------------------------------------------------
139
140If you decide that you'd rather see version 2.6.17, you can modify
141the current branch to point at v2.6.17 instead, with
142
143------------------------------------------------
144$ git reset --hard v2.6.17
145------------------------------------------------
146
J. Bruce Fields81b6c952007-03-18 23:02:14 -0400147Note that if the current branch head was your only reference to a
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500148particular point in history, then resetting that branch may leave you
J. Bruce Fields81b6c952007-03-18 23:02:14 -0400149with no way to find the history it used to point to; so use this command
150carefully.
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500151
J. Bruce Fieldse34caac2007-04-18 00:46:19 -0400152[[understanding-commits]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +0200153=== Understanding History: Commits
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500154
155Every change in the history of a project is represented by a commit.
Dan McGee5162e692007-12-29 00:20:38 -0600156The linkgit:git-show[1] command shows the most recent commit on the
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500157current branch:
158
159------------------------------------------------
160$ git show
J. Bruce Fieldse2618ff2007-08-19 11:14:21 -0400161commit 17cf781661e6d38f737f15f53ab552f1e95960d7
162Author: Linus Torvalds <torvalds@ppc970.osdl.org.(none)>
163Date: Tue Apr 19 14:11:06 2005 -0700
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500164
J. Bruce Fieldse2618ff2007-08-19 11:14:21 -0400165 Remove duplicate getenv(DB_ENVIRONMENT) call
Junio C Hamanoa6080a02007-06-07 00:04:01 -0700166
J. Bruce Fieldse2618ff2007-08-19 11:14:21 -0400167 Noted by Tony Luck.
Junio C Hamanoa6080a02007-06-07 00:04:01 -0700168
J. Bruce Fieldse2618ff2007-08-19 11:14:21 -0400169diff --git a/init-db.c b/init-db.c
170index 65898fa..b002dc6 100644
171--- a/init-db.c
172+++ b/init-db.c
173@@ -7,7 +7,7 @@
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500174
J. Bruce Fieldse2618ff2007-08-19 11:14:21 -0400175 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 Fieldsd19fbc32007-01-07 19:23:49 -0500182------------------------------------------------
183
184As you can see, a commit shows who made the latest change, what they
185did, and why.
186
J. Bruce Fields35121932007-03-03 14:04:42 -0500187Every commit has a 40-hexdigit id, sometimes called the "object name" or the
W. Trevor King1249d8a2013-02-25 17:53:00 -0500188"SHA-1 id", shown on the first line of the `git show` output. You can usually
J. Bruce Fields35121932007-03-03 14:04:42 -0500189refer to a commit by a shorter name, such as a tag or a branch name, but this
190longer name can also be useful. Most importantly, it is a globally unique
191name for this commit: so if you tell somebody else the object name (for
192example in email), then you are guaranteed that name will refer to the same
193commit in their repository that it does in yours (assuming their repository
194has that commit at all). Since the object name is computed as a hash over the
195contents of the commit, you are guaranteed that the commit can never change
196without its name also changing.
197
Thomas Ackermann2de9b712013-01-21 20:17:53 +0100198In fact, in <<git-concepts>> we shall see that everything stored in Git
J. Bruce Fields35121932007-03-03 14:04:42 -0500199history, including file data and directory contents, is stored in an object
200with a name that is a hash of its contents.
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500201
J. Bruce Fieldse34caac2007-04-18 00:46:19 -0400202[[understanding-reachability]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +0200203==== Understanding history: commits, parents, and reachability
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500204
205Every commit (except the very first commit in a project) also has a
206parent commit which shows what happened before this commit.
207Following the chain of parents will eventually take you back to the
208beginning of the project.
209
Thomas Ackermann2de9b712013-01-21 20:17:53 +0100210However, the commits do not form a simple list; Git allows lines of
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500211development to diverge and then reconverge, and the point where two
212lines of development reconverge is called a "merge". The commit
213representing a merge can therefore have more than one parent, with
214each parent representing the most recent commit on one of the lines
215of development leading to that point.
216
Dan McGee5162e692007-12-29 00:20:38 -0600217The best way to see how this works is using the linkgit:gitk[1]
Thomas Ackermann2de9b712013-01-21 20:17:53 +0100218command; running gitk now on a Git repository and looking for merge
Thomas Ackermannddd4dde2013-08-27 19:59:21 +0200219commits will help understand how Git organizes history.
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500220
221In the following, we say that commit X is "reachable" from commit Y
222if commit X is an ancestor of commit Y. Equivalently, you could say
Brian Hetro02783072007-08-23 20:44:13 -0400223that Y is a descendant of X, or that there is a chain of parents
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500224leading from commit Y to commit X.
225
J. Bruce Fieldse34caac2007-04-18 00:46:19 -0400226[[history-diagrams]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +0200227==== Understanding history: History diagrams
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500228
Thomas Ackermann2de9b712013-01-21 20:17:53 +0100229We will sometimes represent Git history using diagrams like the one
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500230below. Commits are shown as "o", and the links between them with
231lines drawn with - / and \. Time goes left to right:
232
J. Bruce Fields1dc71a92007-03-10 22:38:13 -0500233
234................................................
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500235 o--o--o <-- Branch A
236 /
237 o--o--o <-- master
238 \
239 o--o--o <-- Branch B
J. Bruce Fields1dc71a92007-03-10 22:38:13 -0500240................................................
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500241
242If we need to talk about a particular commit, the character "o" may
243be replaced with another letter or number.
244
J. Bruce Fieldse34caac2007-04-18 00:46:19 -0400245[[what-is-a-branch]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +0200246==== Understanding history: What is a branch?
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500247
J. Bruce Fields81b6c952007-03-18 23:02:14 -0400248When we need to be precise, we will use the word "branch" to mean a line
249of development, and "branch head" (or just "head") to mean a reference
250to the most recent commit on a branch. In the example above, the branch
251head named "A" is a pointer to one particular commit, but we refer to
252the line of three commits leading up to that point as all being part of
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500253"branch A".
254
J. Bruce Fields81b6c952007-03-18 23:02:14 -0400255However, when no confusion will result, we often just use the term
256"branch" both for branches and for branch heads.
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500257
J. Bruce Fieldse34caac2007-04-18 00:46:19 -0400258[[manipulating-branches]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +0200259=== Manipulating branches
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500260
261Creating, deleting, and modifying branches is quick and easy; here's
262a summary of the commands:
263
W. Trevor King1249d8a2013-02-25 17:53:00 -0500264`git branch`::
Thomas Ackermanndf47da72013-08-27 20:02:08 +0200265 list all branches.
W. Trevor King1249d8a2013-02-25 17:53:00 -0500266`git branch <branch>`::
267 create a new branch named `<branch>`, referencing the same
Thomas Ackermanndf47da72013-08-27 20:02:08 +0200268 point in history as the current branch.
W. Trevor King1249d8a2013-02-25 17:53:00 -0500269`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 Ackermanndf47da72013-08-27 20:02:08 +0200272 including using a branch name or a tag name.
W. Trevor King1249d8a2013-02-25 17:53:00 -0500273`git branch -d <branch>`::
Thomas Ackermanndf47da72013-08-27 20:02:08 +0200274 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 King1249d8a2013-02-25 17:53:00 -0500277`git branch -D <branch>`::
Thomas Ackermanndf47da72013-08-27 20:02:08 +0200278 delete the branch `<branch>` irrespective of its merged status.
Nguyễn Thái Ngọc Duy328c6cb2019-03-29 17:39:19 +0700279`git switch <branch>`::
W. Trevor King1249d8a2013-02-25 17:53:00 -0500280 make the current branch `<branch>`, updating the working
Thomas Ackermanndf47da72013-08-27 20:02:08 +0200281 directory to reflect the version referenced by `<branch>`.
Nguyễn Thái Ngọc Duy328c6cb2019-03-29 17:39:19 +0700282`git switch -c <new> <start-point>`::
W. Trevor King1249d8a2013-02-25 17:53:00 -0500283 create a new branch `<new>` referencing `<start-point>`, and
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500284 check it out.
285
J. Bruce Fields72a76c92007-04-16 00:37:14 -0400286The special symbol "HEAD" can always be used to refer to the current
W. Trevor King1249d8a2013-02-25 17:53:00 -0500287branch. In fact, Git uses a file named `HEAD` in the `.git` directory
288to remember which branch is current:
J. Bruce Fields72a76c92007-04-16 00:37:14 -0400289
290------------------------------------------------
291$ cat .git/HEAD
292ref: refs/heads/master
293------------------------------------------------
294
J. Bruce Fields25d9f3f2007-04-16 00:37:16 -0400295[[detached-head]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +0200296=== Examining an old version without creating a new branch
J. Bruce Fields72a76c92007-04-16 00:37:14 -0400297
Nguyễn Thái Ngọc Duy328c6cb2019-03-29 17:39:19 +0700298The `git switch` command normally expects a branch head, but will also
299accept an arbitrary commit when invoked with --detach; for example,
300you can check out the commit referenced by a tag:
J. Bruce Fields72a76c92007-04-16 00:37:14 -0400301
302------------------------------------------------
Nguyễn Thái Ngọc Duy328c6cb2019-03-29 17:39:19 +0700303$ git switch --detach v2.6.17
Thomas Ackermann95f9be52013-08-27 19:56:04 +0200304Note: checking out 'v2.6.17'.
305
306You are in 'detached HEAD' state. You can look around, make experimental
307changes and commit them, and you can discard any commits you make in this
Nguyễn Thái Ngọc Duy328c6cb2019-03-29 17:39:19 +0700308state without impacting any branches by performing another switch.
Thomas Ackermann95f9be52013-08-27 19:56:04 +0200309
310If you want to create a new branch to retain commits you create, you may
Nguyễn Thái Ngọc Duy328c6cb2019-03-29 17:39:19 +0700311do so (now or later) by using -c with the switch command again. Example:
Thomas Ackermann95f9be52013-08-27 19:56:04 +0200312
Nguyễn Thái Ngọc Duy328c6cb2019-03-29 17:39:19 +0700313 git switch -c new_branch_name
Thomas Ackermann95f9be52013-08-27 19:56:04 +0200314
Ann T Ropeaca69d4d2017-12-06 01:20:42 +0100315HEAD is now at 427abfa Linux v2.6.17
J. Bruce Fields72a76c92007-04-16 00:37:14 -0400316------------------------------------------------
317
Felipe Contrerasa6e5ef72009-04-04 12:38:27 +0300318The HEAD then refers to the SHA-1 of the commit instead of to a branch,
J. Bruce Fields72a76c92007-04-16 00:37:14 -0400319and git branch shows that you are no longer on a branch:
320
321------------------------------------------------
322$ cat .git/HEAD
323427abfa28afedffadfca9dd8b067eb6d36bac53f
J. Bruce Fields953f3d62007-04-18 00:20:46 -0400324$ git branch
Thomas Ackermann95f9be52013-08-27 19:56:04 +0200325* (detached from v2.6.17)
J. Bruce Fields72a76c92007-04-16 00:37:14 -0400326 master
327------------------------------------------------
328
329In this case we say that the HEAD is "detached".
330
J. Bruce Fields953f3d62007-04-18 00:20:46 -0400331This is an easy way to check out a particular version without having to
332make 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 Fieldsd19fbc32007-01-07 19:23:49 -0500334
J. Bruce Fieldse34caac2007-04-18 00:46:19 -0400335[[examining-remote-branches]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +0200336=== Examining branches from a remote repository
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500337
338The "master" branch that was created at the time you cloned is a copy
339of the HEAD in the repository that you cloned from. That repository
340may also have had other branches, though, and your local repository
Matthieu Moy66a062a2010-11-02 22:06:20 +0100341keeps branches which track each of those remote branches, called
342remote-tracking branches, which you
W. Trevor King1249d8a2013-02-25 17:53:00 -0500343can view using the `-r` option to linkgit:git-branch[1]:
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500344
345------------------------------------------------
346$ git branch -r
347 origin/HEAD
348 origin/html
349 origin/maint
350 origin/man
351 origin/master
352 origin/next
Johannes Schindelin828197d2020-06-25 12:18:57 +0000353 origin/seen
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500354 origin/todo
355------------------------------------------------
356
Matthieu Moy66a062a2010-11-02 22:06:20 +0100357In this example, "origin" is called a remote repository, or "remote"
358for short. The branches of this repository are called "remote
359branches" from our point of view. The remote-tracking branches listed
360above were created based on the remote branches at clone time and will
W. Trevor King1249d8a2013-02-25 17:53:00 -0500361be updated by `git fetch` (hence `git pull`) and `git push`. See
Matthieu Moy66a062a2010-11-02 22:06:20 +0100362<<Updating-a-repository-With-git-fetch>> for details.
363
Jonathan Nieder45dfd402010-11-02 16:31:27 +0100364You might want to build on one of these remote-tracking branches
365on a branch of your own, just as you would for a tag:
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500366
367------------------------------------------------
Nguyễn Thái Ngọc Duy328c6cb2019-03-29 17:39:19 +0700368$ git switch -c my-todo-copy origin/todo
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500369------------------------------------------------
370
W. Trevor King1249d8a2013-02-25 17:53:00 -0500371You can also check out `origin/todo` directly to examine it or
Jonathan Nieder45dfd402010-11-02 16:31:27 +0100372write a one-off patch. See <<detached-head,detached head>>.
373
Thomas Ackermann2de9b712013-01-21 20:17:53 +0100374Note that the name "origin" is just the name that Git uses by default
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500375to refer to the repository that you cloned from.
376
377[[how-git-stores-references]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +0200378=== Naming branches, tags, and other references
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500379
380Branches, remote-tracking branches, and tags are all references to
J. Bruce Fieldsf60b9642007-01-21 22:31:07 -0500381commits. All references are named with a slash-separated path name
W. Trevor King1249d8a2013-02-25 17:53:00 -0500382starting with `refs`; the names we've been using so far are actually
J. Bruce Fieldsf60b9642007-01-21 22:31:07 -0500383shorthand:
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500384
W. Trevor King1249d8a2013-02-25 17:53:00 -0500385 - 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 Fieldsd19fbc32007-01-07 19:23:49 -0500388
J. Bruce Fieldsf60b9642007-01-21 22:31:07 -0500389The full name is occasionally useful if, for example, there ever
390exists a tag and a branch with the same name.
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500391
W. Trevor King1249d8a2013-02-25 17:53:00 -0500392(Newly created refs are actually stored in the `.git/refs` directory,
J. Bruce Fieldsfc74ecc2007-09-09 22:07:02 -0400393under the path given by their name. However, for efficiency reasons
394they may also be packed together in a single file; see
Dan McGee5162e692007-12-29 00:20:38 -0600395linkgit:git-pack-refs[1]).
J. Bruce Fieldsfc74ecc2007-09-09 22:07:02 -0400396
J. Bruce Fieldsc64415e2007-05-07 00:56:45 -0400397As another useful shortcut, the "HEAD" of a repository can be referred
398to just using the name of that repository. So, for example, "origin"
399is usually a shortcut for the HEAD branch in the repository "origin".
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500400
Thomas Ackermann2de9b712013-01-21 20:17:53 +0100401For the complete list of paths which Git checks for references, and
J. Bruce Fieldsf60b9642007-01-21 22:31:07 -0500402the order it uses to decide which to choose when there are multiple
403references with the same shorthand name, see the "SPECIFYING
Jonathan Nieder9d83e382010-10-11 11:03:32 -0500404REVISIONS" section of linkgit:gitrevisions[7].
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500405
Junio C Hamanoaa971cb2008-12-07 18:38:46 -0800406[[Updating-a-repository-With-git-fetch]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +0200407=== Updating a repository with git fetch
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500408
Jeremiah Mahler3c735e02014-05-27 19:23:32 -0700409After you clone a repository and commit a few changes of your own, you
410may wish to check the original repository for updates.
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500411
Jeremiah Mahler3c735e02014-05-27 19:23:32 -0700412The `git-fetch` command, with no arguments, will update all of the
413remote-tracking branches to the latest version found in the original
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500414repository. 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 Fieldse34caac2007-04-18 00:46:19 -0400417[[fetching-branches]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +0200418=== Fetching branches from other repositories
J. Bruce Fieldsd5cd5de2007-01-09 00:18:09 -0500419
420You can also track branches from repositories other than the one you
Dan McGee5162e692007-12-29 00:20:38 -0600421cloned from, using linkgit:git-remote[1]:
J. Bruce Fieldsd5cd5de2007-01-09 00:18:09 -0500422
423-------------------------------------------------
W. Trevor King34a25d42013-06-22 10:46:26 -0400424$ git remote add staging git://git.kernel.org/.../gregkh/staging.git
425$ git fetch staging
426...
427From 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 Fieldsd5cd5de2007-01-09 00:18:09 -0500431-------------------------------------------------
432
433New remote-tracking branches will be stored under the shorthand name
W. Trevor King34a25d42013-06-22 10:46:26 -0400434that you gave `git remote add`, in this case `staging`:
J. Bruce Fieldsd5cd5de2007-01-09 00:18:09 -0500435
436-------------------------------------------------
437$ git branch -r
W. Trevor King34a25d42013-06-22 10:46:26 -0400438 origin/HEAD -> origin/master
439 origin/master
440 staging/master
441 staging/staging-linus
442 staging/staging-next
J. Bruce Fieldsd5cd5de2007-01-09 00:18:09 -0500443-------------------------------------------------
444
W. Trevor King1249d8a2013-02-25 17:53:00 -0500445If you run `git fetch <remote>` later, the remote-tracking branches
446for the named `<remote>` will be updated.
J. Bruce Fieldsd5cd5de2007-01-09 00:18:09 -0500447
W. Trevor King1249d8a2013-02-25 17:53:00 -0500448If you examine the file `.git/config`, you will see that Git has added
J. Bruce Fieldsd5cd5de2007-01-09 00:18:09 -0500449a new stanza:
450
451-------------------------------------------------
452$ cat .git/config
453...
W. Trevor King34a25d42013-06-22 10:46:26 -0400454[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 Fieldsd5cd5de2007-01-09 00:18:09 -0500457...
458-------------------------------------------------
459
Thomas Ackermann2de9b712013-01-21 20:17:53 +0100460This is what causes Git to track the remote's branches; you may modify
W. Trevor King1249d8a2013-02-25 17:53:00 -0500461or delete these configuration options by editing `.git/config` with a
J. Bruce Fieldsfc90c532007-01-29 00:17:51 -0500462text editor. (See the "CONFIGURATION FILE" section of
Dan McGee5162e692007-12-29 00:20:38 -0600463linkgit:git-config[1] for details.)
J. Bruce Fieldsd5cd5de2007-01-09 00:18:09 -0500464
J. Bruce Fieldse34caac2007-04-18 00:46:19 -0400465[[exploring-git-history]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +0200466== Exploring Git history
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500467
468Git is best thought of as a tool for storing the history of a
469collection of files. It does this by storing compressed snapshots of
Junio C Hamano11308452007-07-24 01:58:51 -0700470the contents of a file hierarchy, together with "commits" which show
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500471the relationships between these snapshots.
472
473Git provides extremely flexible and fast tools for exploring the
474history of a project.
475
Mike Colemanaacd4042007-02-02 00:25:30 -0600476We start with one specialized tool that is useful for finding the
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500477commit that introduced a bug into a project.
478
J. Bruce Fieldse34caac2007-04-18 00:46:19 -0400479[[using-bisect]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +0200480=== How to use bisect to find a regression
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500481
482Suppose 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
484regression is to perform a brute-force search through the project's
485history to find the particular commit that caused the problem. The
Dan McGee5162e692007-12-29 00:20:38 -0600486linkgit:git-bisect[1] command can help you do this:
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500487
488-------------------------------------------------
489$ git bisect start
490$ git bisect good v2.6.18
491$ git bisect bad master
492Bisecting: 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 King1249d8a2013-02-25 17:53:00 -0500496If you run `git branch` at this point, you'll see that Git has
Christian Couder0e257902008-07-31 05:22:40 +0200497temporarily moved you in "(no branch)". HEAD is now detached from any
Ann T Ropeaf61d89e2017-12-03 22:27:38 +0100498branch and points directly to a commit (with commit id 65934) that
Christian Couder0e257902008-07-31 05:22:40 +0200499is reachable from "master" but not from v2.6.18. Compile and test it,
500and see whether it crashes. Assume it does crash. Then:
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500501
502-------------------------------------------------
503$ git bisect bad
504Bisecting: 1769 revisions left to test after this
505[7eff82c8b1511017ae605f0c99ac275a7e21b867] i2c-core: Drop useless bitmaskings
506-------------------------------------------------
507
Thomas Ackermann2de9b712013-01-21 20:17:53 +0100508checks out an older version. Continue like this, telling Git at each
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500509stage whether the version it gives you is good or bad, and notice
510that the number of revisions left to test is cut approximately in
511half each time.
512
513After about 13 tests (in this case), it will output the commit id of
514the guilty commit. You can then examine the commit with
Dan McGee5162e692007-12-29 00:20:38 -0600515linkgit:git-show[1], find out who wrote it, and mail them your bug
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500516report with the commit id. Finally, run
517
518-------------------------------------------------
519$ git bisect reset
520-------------------------------------------------
521
Christian Couder0e257902008-07-31 05:22:40 +0200522to return you to the branch you were on before.
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500523
Felipe Contreras6127c082009-04-04 12:38:23 +0300524Note that the version which `git bisect` checks out for you at each
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500525point is just a suggestion, and you're free to try a different
526version if you think it would be a good idea. For example,
527occasionally you may land on a commit that broke something unrelated;
528run
529
530-------------------------------------------------
Jakub Narebski04483522007-04-03 18:27:28 +0200531$ git bisect visualize
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500532-------------------------------------------------
533
534which will run gitk and label the commit it chose with a marker that
Eric Hanchrow843c81d2008-07-08 13:00:30 -0700535says "bisect". Choose a safe-looking commit nearby, note its commit
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500536id, and check it out with:
537
538-------------------------------------------------
Ann T Ropeaf61d89e2017-12-03 22:27:38 +0100539$ git reset --hard fb47ddb2db
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500540-------------------------------------------------
541
W. Trevor King1249d8a2013-02-25 17:53:00 -0500542then test, run `bisect good` or `bisect bad` as appropriate, and
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500543continue.
544
W. Trevor King1249d8a2013-02-25 17:53:00 -0500545Instead of `git bisect visualize` and then `git reset --hard
Ann T Ropeaf61d89e2017-12-03 22:27:38 +0100546fb47ddb2db`, you might just want to tell Git that you want to skip
Christian Couder0e257902008-07-31 05:22:40 +0200547the current commit:
548
549-------------------------------------------------
550$ git bisect skip
551-------------------------------------------------
552
Thomas Ackermann2de9b712013-01-21 20:17:53 +0100553In this case, though, Git may not eventually be able to tell the first
Ralf Wildenhuesa0178ae2008-11-27 08:32:01 +0100554bad one between some first skipped commits and a later bad commit.
Christian Couder0e257902008-07-31 05:22:40 +0200555
556There are also ways to automate the bisecting process if you have a
557test script that can tell a good from a bad commit. See
W. Trevor King1249d8a2013-02-25 17:53:00 -0500558linkgit:git-bisect[1] for more information about this and other `git
559bisect` features.
Christian Couder0e257902008-07-31 05:22:40 +0200560
J. Bruce Fieldse34caac2007-04-18 00:46:19 -0400561[[naming-commits]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +0200562=== Naming commits
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500563
564We have seen several ways of naming commits already:
565
J. Bruce Fieldsd55ae922007-01-29 02:16:45 -0500566 - 40-hexdigit object name
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500567 - 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 Hamanoeb6ae7f2007-01-10 18:11:53 -0800574There are many more; see the "SPECIFYING REVISIONS" section of the
Jonathan Nieder9d83e382010-10-11 11:03:32 -0500575linkgit:gitrevisions[7] man page for the complete list of ways to
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500576name revisions. Some examples:
577
578-------------------------------------------------
J. Bruce Fieldsd55ae922007-01-29 02:16:45 -0500579$ git show fb47ddb2 # the first few characters of the object name
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500580 # 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
586Recall that merge commits may have more than one parent; by default,
W. Trevor King1249d8a2013-02-25 17:53:00 -0500587`^` and `~` follow the first parent listed in the commit, but you can
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500588also 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
595In addition to HEAD, there are several other special names for
596commits:
597
598Merges (to be discussed later), as well as operations such as
Felipe Contreras6127c082009-04-04 12:38:23 +0300599`git reset`, which change the currently checked-out commit, generally
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500600set ORIG_HEAD to the value HEAD had before the current operation.
601
Felipe Contreras6127c082009-04-04 12:38:23 +0300602The `git fetch` operation always stores the head of the last fetched
603branch in FETCH_HEAD. For example, if you run `git fetch` without
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500604specifying a local branch as the target of the operation
605
606-------------------------------------------------
607$ git fetch git://example.com/proj.git theirbranch
608-------------------------------------------------
609
610the fetched commits will still be available from FETCH_HEAD.
611
612When we discuss merges we'll also see the special name MERGE_HEAD,
613which refers to the other branch that we're merging in to the current
614branch.
615
Dan McGee5162e692007-12-29 00:20:38 -0600616The linkgit:git-rev-parse[1] command is a low-level command that is
J. Bruce Fieldsd55ae922007-01-29 02:16:45 -0500617occasionally useful for translating some name for a commit to the object
618name for that commit:
J. Bruce Fieldsaec053b2007-01-10 23:17:00 -0500619
620-------------------------------------------------
621$ git rev-parse origin
622e05db0fd4f31dde7005f075a84f96b360d05984b
623-------------------------------------------------
624
J. Bruce Fieldse34caac2007-04-18 00:46:19 -0400625[[creating-tags]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +0200626=== Creating tags
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500627
628We can also create a tag to refer to a particular commit; after
629running
630
631-------------------------------------------------
Jakub Narebski04483522007-04-03 18:27:28 +0200632$ git tag stable-1 1b2e1d63ff
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500633-------------------------------------------------
634
W. Trevor King1249d8a2013-02-25 17:53:00 -0500635You can use `stable-1` to refer to the commit 1b2e1d63ff.
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500636
J. Bruce Fieldsc64415e2007-05-07 00:56:45 -0400637This creates a "lightweight" tag. If you would also like to include a
638comment with the tag, and possibly sign it cryptographically, then you
Dan McGee5162e692007-12-29 00:20:38 -0600639should create a tag object instead; see the linkgit:git-tag[1] man page
J. Bruce Fieldsc64415e2007-05-07 00:56:45 -0400640for details.
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500641
J. Bruce Fieldse34caac2007-04-18 00:46:19 -0400642[[browsing-revisions]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +0200643=== Browsing revisions
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500644
Dan McGee5162e692007-12-29 00:20:38 -0600645The linkgit:git-log[1] command can show lists of commits. On its
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500646own, it shows all commits reachable from the parent commit; but you
647can 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
662And of course you can combine all of these; the following finds
W. Trevor King1249d8a2013-02-25 17:53:00 -0500663commits since v2.5 which touch the `Makefile` or any file under `fs`:
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500664
665-------------------------------------------------
666$ git log v2.5.. Makefile fs/
667-------------------------------------------------
668
669You can also ask git log to show patches:
670
671-------------------------------------------------
672$ git log -p
673-------------------------------------------------
674
W. Trevor King1249d8a2013-02-25 17:53:00 -0500675See the `--pretty` option in the linkgit:git-log[1] man page for more
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500676display options.
677
678Note that git log starts with the most recent commit and works
Thomas Ackermann2de9b712013-01-21 20:17:53 +0100679backwards through the parents; however, since Git history can contain
Pavel Roskin3dff5372007-02-03 23:49:16 -0500680multiple independent lines of development, the particular order that
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500681commits are listed in may be somewhat arbitrary.
682
J. Bruce Fieldse34caac2007-04-18 00:46:19 -0400683[[generating-diffs]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +0200684=== Generating diffs
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500685
686You can generate diffs between any two versions using
Dan McGee5162e692007-12-29 00:20:38 -0600687linkgit:git-diff[1]:
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500688
689-------------------------------------------------
690$ git diff master..test
691-------------------------------------------------
692
J. Bruce Fields5b98d9b2007-11-18 19:18:27 -0500693That will produce the diff between the tips of the two branches. If
694you'd prefer to find the diff from their common ancestor to test, you
695can use three dots instead of two:
696
697-------------------------------------------------
698$ git diff master...test
699-------------------------------------------------
700
701Sometimes what you want instead is a set of patches; for this you can
Dan McGee5162e692007-12-29 00:20:38 -0600702use linkgit:git-format-patch[1]:
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500703
704-------------------------------------------------
705$ git format-patch master..test
706-------------------------------------------------
707
708will generate a file with a patch for each commit reachable from test
J. Bruce Fields5b98d9b2007-11-18 19:18:27 -0500709but not from master.
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500710
J. Bruce Fieldse34caac2007-04-18 00:46:19 -0400711[[viewing-old-file-versions]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +0200712=== Viewing old file versions
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500713
714You can always view an old version of a file by just checking out the
715correct revision first. But sometimes it is more convenient to be
716able to view an old version of a single file without checking
717anything out; this command does that:
718
719-------------------------------------------------
720$ git show v2.5:fs/locks.c
721-------------------------------------------------
722
723Before the colon may be anything that names a commit, and after it
Thomas Ackermann2de9b712013-01-21 20:17:53 +0100724may be any path to a file tracked by Git.
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500725
J. Bruce Fieldse34caac2007-04-18 00:46:19 -0400726[[history-examples]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +0200727=== Examples
J. Bruce Fieldsaec053b2007-01-10 23:17:00 -0500728
J. Bruce Fields46acd3f2007-05-13 02:14:45 -0400729[[counting-commits-on-a-branch]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +0200730==== Counting the number of commits on a branch
J. Bruce Fields46acd3f2007-05-13 02:14:45 -0400731
W. Trevor King1249d8a2013-02-25 17:53:00 -0500732Suppose you want to know how many commits you've made on `mybranch`
733since it diverged from `origin`:
J. Bruce Fields46acd3f2007-05-13 02:14:45 -0400734
735-------------------------------------------------
736$ git log --pretty=oneline origin..mybranch | wc -l
737-------------------------------------------------
738
739Alternatively, you may often see this sort of thing done with the
Felipe Contrerasa6e5ef72009-04-04 12:38:27 +0300740lower-level command linkgit:git-rev-list[1], which just lists the SHA-1's
J. Bruce Fields46acd3f2007-05-13 02:14:45 -0400741of all the given commits:
742
743-------------------------------------------------
744$ git rev-list origin..mybranch | wc -l
745-------------------------------------------------
746
J. Bruce Fieldse34caac2007-04-18 00:46:19 -0400747[[checking-for-equal-branches]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +0200748==== Check whether two branches point at the same history
J. Bruce Fieldsaec053b2007-01-10 23:17:00 -0500749
750Suppose you want to check whether two branches point at the same point
751in history.
752
753-------------------------------------------------
754$ git diff origin..master
755-------------------------------------------------
756
J. Bruce Fields69f7ad72007-01-14 16:29:40 -0500757will tell you whether the contents of the project are the same at the
758two branches; in theory, however, it's possible that the same project
759contents could have been arrived at by two different historical
J. Bruce Fieldsd55ae922007-01-29 02:16:45 -0500760routes. You could compare the object names:
J. Bruce Fieldsaec053b2007-01-10 23:17:00 -0500761
762-------------------------------------------------
763$ git rev-list origin
764e05db0fd4f31dde7005f075a84f96b360d05984b
765$ git rev-list master
766e05db0fd4f31dde7005f075a84f96b360d05984b
767-------------------------------------------------
768
W. Trevor King1249d8a2013-02-25 17:53:00 -0500769Or you could recall that the `...` operator selects all commits
Thomas Ackermannddd4dde2013-08-27 19:59:21 +0200770reachable from either one reference or the other but not
W. Trevor Kingddd23692013-02-10 10:10:36 -0500771both; so
J. Bruce Fieldsaec053b2007-01-10 23:17:00 -0500772
773-------------------------------------------------
774$ git log origin...master
775-------------------------------------------------
776
777will return no commits when the two branches are equal.
778
J. Bruce Fieldse34caac2007-04-18 00:46:19 -0400779[[finding-tagged-descendants]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +0200780==== Find first tagged version including a given fix
J. Bruce Fieldsaec053b2007-01-10 23:17:00 -0500781
J. Bruce Fields69f7ad72007-01-14 16:29:40 -0500782Suppose you know that the commit e05db0fd fixed a certain problem.
783You'd like to find the earliest tagged release that contains that
784fix.
785
786Of course, there may be more than one answer--if the history branched
787after commit e05db0fd, then there could be multiple "earliest" tagged
788releases.
789
790You could just visually inspect the commits since e05db0fd:
791
792-------------------------------------------------
793$ gitk e05db0fd..
794-------------------------------------------------
795
Thomas Ackermannddd4dde2013-08-27 19:59:21 +0200796or you can use linkgit:git-name-rev[1], which will give the commit a
J. Bruce Fieldsb181d572007-01-27 01:03:07 -0500797name based on any tag it finds pointing to one of the commit's
798descendants:
799
800-------------------------------------------------
Jakub Narebski04483522007-04-03 18:27:28 +0200801$ git name-rev --tags e05db0fd
J. Bruce Fieldsb181d572007-01-27 01:03:07 -0500802e05db0fd tags/v1.5.0-rc1^0~23
803-------------------------------------------------
804
Dan McGee5162e692007-12-29 00:20:38 -0600805The linkgit:git-describe[1] command does the opposite, naming the
J. Bruce Fieldsb181d572007-01-27 01:03:07 -0500806revision using a tag on which the given commit is based:
807
808-------------------------------------------------
809$ git describe e05db0fd
Jakub Narebski04483522007-04-03 18:27:28 +0200810v1.5.0-rc0-260-ge05db0f
J. Bruce Fieldsb181d572007-01-27 01:03:07 -0500811-------------------------------------------------
812
813but that may sometimes help you guess which tags might come after the
814given commit.
815
816If you just want to verify whether a given tagged version contains a
Dan McGee5162e692007-12-29 00:20:38 -0600817given commit, you could use linkgit:git-merge-base[1]:
J. Bruce Fieldsb181d572007-01-27 01:03:07 -0500818
819-------------------------------------------------
820$ git merge-base e05db0fd v1.5.0-rc1
821e05db0fd4f31dde7005f075a84f96b360d05984b
822-------------------------------------------------
823
824The merge-base command finds a common ancestor of the given commits,
825and always returns one or the other in the case where one is a
826descendant of the other; so the above output shows that e05db0fd
827actually is an ancestor of v1.5.0-rc1.
828
829Alternatively, note that
830
831-------------------------------------------------
J. Bruce Fields4a7979c2007-01-29 01:55:33 -0500832$ git log v1.5.0-rc1..e05db0fd
J. Bruce Fieldsb181d572007-01-27 01:03:07 -0500833-------------------------------------------------
834
J. Bruce Fields4a7979c2007-01-29 01:55:33 -0500835will produce empty output if and only if v1.5.0-rc1 includes e05db0fd,
J. Bruce Fieldsb181d572007-01-27 01:03:07 -0500836because it outputs only commits that are not reachable from v1.5.0-rc1.
J. Bruce Fieldsaec053b2007-01-10 23:17:00 -0500837
Dan McGee5162e692007-12-29 00:20:38 -0600838As yet another alternative, the linkgit:git-show-branch[1] command lists
J. Bruce Fields4a7979c2007-01-29 01:55:33 -0500839the commits reachable from its arguments with a display on the left-hand
Thomas Ackermannddd4dde2013-08-27 19:59:21 +0200840side that indicates which arguments that commit is reachable from.
841So, if you run something like
J. Bruce Fields4a7979c2007-01-29 01:55:33 -0500842
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
846available
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 Ackermannddd4dde2013-08-27 19:59:21 +0200853then a line like
J. Bruce Fields4a7979c2007-01-29 01:55:33 -0500854
855-------------------------------------------------
856+ ++ [e05db0fd] Fix warnings in sha1_file.c - use C99 printf format if
857available
858-------------------------------------------------
859
Thomas Ackermannddd4dde2013-08-27 19:59:21 +0200860shows that e05db0fd is reachable from itself, from v1.5.0-rc1,
861and from v1.5.0-rc2, and not from v1.5.0-rc0.
J. Bruce Fields4a7979c2007-01-29 01:55:33 -0500862
J. Bruce Fields629d9f72007-05-13 22:58:06 -0400863[[showing-commits-unique-to-a-branch]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +0200864==== Showing commits unique to a given branch
J. Bruce Fields629d9f72007-05-13 22:58:06 -0400865
866Suppose you would like to see all the commits reachable from the branch
W. Trevor King1249d8a2013-02-25 17:53:00 -0500867head named `master` but not from any other head in your repository.
J. Bruce Fields629d9f72007-05-13 22:58:06 -0400868
869We can list all the heads in this repository with
Dan McGee5162e692007-12-29 00:20:38 -0600870linkgit:git-show-ref[1]:
J. Bruce Fields629d9f72007-05-13 22:58:06 -0400871
872-------------------------------------------------
873$ git show-ref --heads
874bf62196b5e363d73353a9dcf094c59595f3153b7 refs/heads/core-tutorial
875db768d5504c1bb46f63ee9d6e1772bd047e05bf9 refs/heads/maint
876a07157ac624b2524a059a3414e99f6f44bebc1e7 refs/heads/master
87724dbc180ea14dc1aebe09f14c8ecf32010690627 refs/heads/tutorial-2
8781e87486ae06626c2f31eaa63d26fc0fd646c8af2 refs/heads/tutorial-fixes
879-------------------------------------------------
880
W. Trevor King1249d8a2013-02-25 17:53:00 -0500881We can get just the branch-head names, and remove `master`, with
J. Bruce Fields629d9f72007-05-13 22:58:06 -0400882the help of the standard utilities cut and grep:
883
884-------------------------------------------------
885$ git show-ref --heads | cut -d' ' -f2 | grep -v '^refs/heads/master'
886refs/heads/core-tutorial
887refs/heads/maint
888refs/heads/tutorial-2
889refs/heads/tutorial-fixes
890-------------------------------------------------
891
892And then we can ask to see all the commits reachable from master
893but 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
900Obviously, endless variations are possible; for example, to see all
901commits reachable from some head but not from any tag in the repository:
902
903-------------------------------------------------
Steffen Prohaskac78974f2007-05-26 21:16:27 +0200904$ gitk $( git show-ref --heads ) --not $( git show-ref --tags )
J. Bruce Fields629d9f72007-05-13 22:58:06 -0400905-------------------------------------------------
906
Jonathan Nieder9d83e382010-10-11 11:03:32 -0500907(See linkgit:gitrevisions[7] for explanations of commit-selecting
J. Bruce Fields629d9f72007-05-13 22:58:06 -0400908syntax such as `--not`.)
909
J. Bruce Fields82c8bf22007-05-13 00:14:40 -0400910[[making-a-release]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +0200911==== Creating a changelog and tarball for a software release
J. Bruce Fields82c8bf22007-05-13 00:14:40 -0400912
Dan McGee5162e692007-12-29 00:20:38 -0600913The linkgit:git-archive[1] command can create a tar or zip archive from
J. Bruce Fields82c8bf22007-05-13 00:14:40 -0400914any version of a project; for example:
915
916-------------------------------------------------
W. Trevor King7ed16902013-02-17 19:16:01 -0500917$ git archive -o latest.tar.gz --prefix=project/ HEAD
J. Bruce Fields82c8bf22007-05-13 00:14:40 -0400918-------------------------------------------------
919
W. Trevor King7ed16902013-02-17 19:16:01 -0500920will use HEAD to produce a gzipped tar archive in which each filename
921is preceded by `project/`. The output file format is inferred from
922the output file extension if possible, see linkgit:git-archive[1] for
923details.
924
W. Trevor King1249d8a2013-02-25 17:53:00 -0500925Versions of Git older than 1.7.7 don't know about the `tar.gz` format,
W. Trevor King7ed16902013-02-17 19:16:01 -0500926you'll need to use gzip explicitly:
927
928-------------------------------------------------
929$ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz
930-------------------------------------------------
J. Bruce Fields82c8bf22007-05-13 00:14:40 -0400931
932If you're releasing a new version of a software project, you may want
933to simultaneously make a changelog to include in the release
934announcement.
935
936Linus Torvalds, for example, makes new kernel releases by tagging them,
937then running:
938
939-------------------------------------------------
940$ release-script 2.6.12 2.6.13-rc6 2.6.13-rc7
941-------------------------------------------------
942
943where release-script is a shell script that looks like:
944
945-------------------------------------------------
946#!/bin/sh
947stable="$1"
948last="$2"
949new="$3"
950echo "# git tag v$new"
951echo "git archive --prefix=linux-$new/ v$new | gzip -9 > ../linux-$new.tar.gz"
952echo "git diff v$stable v$new | gzip -9 > ../patch-$new.gz"
953echo "git log --no-merges v$new ^v$last > ../ChangeLog-$new"
954echo "git shortlog --no-merges v$new ^v$last > ../ShortLog"
955echo "git diff --stat --summary -M v$last v$new > ../diffstat-$new"
956-------------------------------------------------
957
958and then he just cut-and-pastes the output commands after verifying that
959they look OK.
J. Bruce Fields4a7979c2007-01-29 01:55:33 -0500960
Michael J Grubere1ba4c32010-09-28 13:16:07 +0200961[[Finding-commits-With-given-Content]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +0200962==== Finding commits referencing a file with given content
J. Bruce Fields187b0d82007-05-19 00:37:25 -0400963
964Somebody hands you a copy of a file, and asks which commits modified a
965file such that it contained the given content either before or after the
966commit. You can find out with this:
967
968-------------------------------------------------
Ralf Wildenhues477ff5b2007-10-09 23:02:19 +0200969$ git log --raw --abbrev=40 --pretty=oneline |
J. Bruce Fields187b0d82007-05-19 00:37:25 -0400970 grep -B 1 `git hash-object filename`
971-------------------------------------------------
972
973Figuring out why this works is left as an exercise to the (advanced)
Dan McGee5162e692007-12-29 00:20:38 -0600974student. The linkgit:git-log[1], linkgit:git-diff-tree[1], and
975linkgit:git-hash-object[1] man pages may prove helpful.
J. Bruce Fields187b0d82007-05-19 00:37:25 -0400976
Junio C Hamanoaa971cb2008-12-07 18:38:46 -0800977[[Developing-With-git]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +0200978== Developing with Git
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500979
J. Bruce Fieldse34caac2007-04-18 00:46:19 -0400980[[telling-git-your-name]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +0200981=== Telling Git your name
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500982
W. Trevor King632cc3e2013-02-17 19:15:58 -0500983Before creating any commits, you should introduce yourself to Git.
984The 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
991Which will add the following to a file named `.gitconfig` in your
992home directory:
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500993
994------------------------------------------------
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500995[user]
996 name = Your Name Comes Here
997 email = you@yourdomain.example.com
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -0500998------------------------------------------------
999
W. Trevor King632cc3e2013-02-17 19:15:58 -05001000See the "CONFIGURATION FILE" section of linkgit:git-config[1] for
1001details on the configuration file. The file is plain text, so you can
1002also edit it with your favorite editor.
J. Bruce Fieldsfc90c532007-01-29 00:17:51 -05001003
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001004
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04001005[[creating-a-new-repository]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02001006=== Creating a new repository
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001007
1008Creating a new repository from scratch is very easy:
1009
1010-------------------------------------------------
1011$ mkdir project
1012$ cd project
J. Bruce Fieldsf1d2b472007-01-11 12:44:08 -05001013$ git init
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001014-------------------------------------------------
1015
1016If you have some initial content (say, a tarball):
1017
1018-------------------------------------------------
Henrik Austad0ddd93b2009-01-05 16:25:37 +01001019$ tar xzvf project.tar.gz
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001020$ cd project
J. Bruce Fieldsf1d2b472007-01-11 12:44:08 -05001021$ git init
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001022$ git add . # include everything below ./ in the first commit:
1023$ git commit
1024-------------------------------------------------
1025
1026[[how-to-make-a-commit]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02001027=== How to make a commit
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001028
1029Creating a new commit takes three steps:
1030
1031 1. Making some changes to the working directory using your
1032 favorite editor.
Thomas Ackermann2de9b712013-01-21 20:17:53 +01001033 2. Telling Git about your changes.
1034 3. Creating the commit using the content you told Git about
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001035 in step 2.
1036
1037In practice, you can interleave and repeat steps 1 and 2 as many
1038times as you want: in order to keep track of what you want committed
Thomas Ackermann2de9b712013-01-21 20:17:53 +01001039at step 3, Git maintains a snapshot of the tree's contents in a
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001040special staging area called "the index."
1041
J. Bruce Fields01997b42007-01-10 23:23:37 -05001042At the beginning, the content of the index will be identical to
W. Trevor King1249d8a2013-02-25 17:53:00 -05001043that of the HEAD. The command `git diff --cached`, which shows
J. Bruce Fields01997b42007-01-10 23:23:37 -05001044the difference between the HEAD and the index, should therefore
1045produce no output at that point.
Junio C Hamanoeb6ae7f2007-01-10 18:11:53 -08001046
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001047Modifying the index is easy:
1048
Thomas Ackermannd39765b2013-08-27 20:01:17 +02001049To update the index with the contents of a new or modified file, use
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001050
1051-------------------------------------------------
1052$ git add path/to/file
1053-------------------------------------------------
1054
Thomas Ackermannd39765b2013-08-27 20:01:17 +02001055To remove a file from the index and from the working tree, use
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001056
1057-------------------------------------------------
1058$ git rm path/to/file
1059-------------------------------------------------
1060
1061After each step you can verify that
1062
1063-------------------------------------------------
1064$ git diff --cached
1065-------------------------------------------------
1066
1067always shows the difference between the HEAD and the index file--this
1068is what you'd commit if you created the commit now--and that
1069
1070-------------------------------------------------
1071$ git diff
1072-------------------------------------------------
1073
1074shows the difference between the working tree and the index file.
1075
W. Trevor King1249d8a2013-02-25 17:53:00 -05001076Note that `git add` always adds just the current contents of a file
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001077to the index; further changes to the same file will be ignored unless
Felipe Contreras6127c082009-04-04 12:38:23 +03001078you run `git add` on the file again.
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001079
1080When you're ready, just run
1081
1082-------------------------------------------------
1083$ git commit
1084-------------------------------------------------
1085
Thomas Ackermann2de9b712013-01-21 20:17:53 +01001086and Git will prompt you for a commit message and then create the new
Pavel Roskin3dff5372007-02-03 23:49:16 -05001087commit. Check to make sure it looks like what you expected with
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001088
1089-------------------------------------------------
1090$ git show
1091-------------------------------------------------
1092
1093As a special shortcut,
Junio C Hamanoa6080a02007-06-07 00:04:01 -07001094
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001095-------------------------------------------------
1096$ git commit -a
1097-------------------------------------------------
1098
1099will update the index with any files that you've modified or removed
1100and create a commit, all in one step.
1101
1102A number of commands are useful for keeping track of what you're
1103about to commit:
1104
1105-------------------------------------------------
1106$ git diff --cached # difference between HEAD and the index; what
Junio C Hamano11308452007-07-24 01:58:51 -07001107 # would be committed if you ran "commit" now.
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001108$ 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 Fieldsc64415e2007-05-07 00:56:45 -04001111$ git diff HEAD # difference between HEAD and working tree; what
1112 # would be committed if you ran "commit -a" now.
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001113$ git status # a brief per-file summary of the above.
1114-------------------------------------------------
1115
Dan McGee5162e692007-12-29 00:20:38 -06001116You can also use linkgit:git-gui[1] to create commits, view changes in
J. Bruce Fields407c0c82007-08-05 18:12:37 -04001117the index and the working tree files, and individually select diff hunks
1118for inclusion in the index (by right-clicking on the diff hunk and
1119choosing "Stage Hunk For Commit").
1120
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04001121[[creating-good-commit-messages]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02001122=== Creating good commit messages
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001123
1124Though not required, it's a good idea to begin the commit message
谢致邦 (XIE Zhibang)1627e6b2023-10-08 15:19:26 +00001125with a single short (no more than 50 characters) line summarizing the
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001126change, followed by a blank line and then a more thorough
Jeremy White52ffe992012-09-13 17:27:09 -05001127description. The text up to the first blank line in a commit
1128message is treated as the commit title, and that title is used
Thomas Ackermann2de9b712013-01-21 20:17:53 +01001129throughout Git. For example, linkgit:git-format-patch[1] turns a
Jeremy White52ffe992012-09-13 17:27:09 -05001130commit into email, and it uses the title on the Subject line and the
1131rest of the commit in the body.
1132
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001133
Johan Herland2dc53612007-05-16 02:31:40 +02001134[[ignoring-files]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02001135=== Ignoring files
Johan Herland2dc53612007-05-16 02:31:40 +02001136
Thomas Ackermann2de9b712013-01-21 20:17:53 +01001137A project will often generate files that you do 'not' want to track with Git.
Johan Herland2dc53612007-05-16 02:31:40 +02001138This typically includes files generated by a build process or temporary
Thomas Ackermann2de9b712013-01-21 20:17:53 +01001139backup files made by your editor. Of course, 'not' tracking files with Git
Felipe Contreras6127c082009-04-04 12:38:23 +03001140is just a matter of 'not' calling `git add` on them. But it quickly becomes
Johan Herland2dc53612007-05-16 02:31:40 +02001141annoying to have these untracked files lying around; e.g. they make
Chris Johnsendcb11262009-03-15 06:30:52 -05001142`git add .` practically useless, and they keep showing up in the output of
1143`git status`.
Johan Herland2dc53612007-05-16 02:31:40 +02001144
W. Trevor King1249d8a2013-02-25 17:53:00 -05001145You can tell Git to ignore certain files by creating a file called
1146`.gitignore` in the top level of your working directory, with contents
1147such as:
Johan Herland2dc53612007-05-16 02:31:40 +02001148
1149-------------------------------------------------
1150# Lines starting with '#' are considered comments.
J. Bruce Fields464a8a72007-05-24 20:28:14 -04001151# Ignore any file named foo.txt.
Johan Herland2dc53612007-05-16 02:31:40 +02001152foo.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 McGee5162e692007-12-29 00:20:38 -06001161See linkgit:gitignore[5] for a detailed explanation of the syntax. You can
J. Bruce Fields464a8a72007-05-24 20:28:14 -04001162also place .gitignore files in other directories in your working tree, and they
1163will apply to those directories and their subdirectories. The `.gitignore`
1164files 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
1166patterns (such as patterns matching build output files) would also make sense
1167for other users who clone your repository.
Johan Herland2dc53612007-05-16 02:31:40 +02001168
J. Bruce Fields464a8a72007-05-24 20:28:14 -04001169If 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 King1249d8a2013-02-25 17:53:00 -05001171them in a file in your repository named `.git/info/exclude`, or in any
Nguyễn Thái Ngọc Duyda0005b2015-03-11 16:32:45 -04001172file specified by the `core.excludesFile` configuration variable.
W. Trevor King1249d8a2013-02-25 17:53:00 -05001173Some Git commands can also take exclude patterns directly on the
1174command line. See linkgit:gitignore[5] for the details.
Johan Herland2dc53612007-05-16 02:31:40 +02001175
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04001176[[how-to-merge]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02001177=== How to merge
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001178
1179You can rejoin two diverging branches of development using
Dan McGee5162e692007-12-29 00:20:38 -06001180linkgit:git-merge[1]:
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001181
1182-------------------------------------------------
1183$ git merge branchname
1184-------------------------------------------------
1185
W. Trevor King1249d8a2013-02-25 17:53:00 -05001186merges the development in the branch `branchname` into the current
Matthieu Moye63ec002009-11-22 23:26:18 +01001187branch.
1188
W. Trevor King1249d8a2013-02-25 17:53:00 -05001189A merge is made by combining the changes made in `branchname` and the
Matthieu Moye63ec002009-11-22 23:26:18 +01001190changes made up to the latest commit in your current branch since
1191their histories forked. The work tree is overwritten by the result of
1192the merge when this combining is done cleanly, or overwritten by a
1193half-merged results when this combining results in conflicts.
1194Therefore, if you have uncommitted changes touching the same files as
1195the ones impacted by the merge, Git will refuse to proceed. Most of
1196the time, you will want to commit your changes before you can merge,
1197and if you don't, then linkgit:git-stash[1] can take these changes
1198away while you're doing the merge, and reapply them afterwards.
1199
Ralf Wildenhues6a5d0b02010-01-31 14:24:39 +01001200If the changes are independent enough, Git will automatically complete
Matthieu Moye63ec002009-11-22 23:26:18 +01001201the merge and commit the result (or reuse an existing commit in case
1202of <<fast-forwards,fast-forward>>, see below). On the other hand,
1203if there are conflicts--for example, if the same file is
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001204modified in two different ways in the remote branch and the local
1205branch--then you are warned; the output may look something like this:
1206
1207-------------------------------------------------
J. Bruce Fieldsfabbd8f2007-03-10 21:52:39 -05001208$ git merge next
1209 100% (4/4) done
1210Auto-merged file.txt
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001211CONFLICT (content): Merge conflict in file.txt
1212Automatic merge failed; fix conflicts and then commit the result.
1213-------------------------------------------------
1214
1215Conflict markers are left in the problematic files, and after
1216you resolve the conflicts manually, you can update the index
Thomas Ackermann2de9b712013-01-21 20:17:53 +01001217with the contents and run Git commit, as you normally would when
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001218creating a new file.
1219
1220If you examine the resulting commit using gitk, you will see that it
1221has two parents, one pointing to the top of the current branch, and
1222one to the top of the other branch.
1223
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001224[[resolving-a-merge]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02001225=== Resolving a merge
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001226
Thomas Ackermann2de9b712013-01-21 20:17:53 +01001227When a merge isn't resolved automatically, Git leaves the index and
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001228the working tree in a special state that gives you all the
1229information you need to help resolve the merge.
1230
1231Files with conflicts are marked specially in the index, so until you
Dan McGee5162e692007-12-29 00:20:38 -06001232resolve the problem and update the index, linkgit:git-commit[1] will
J. Bruce Fieldsef561ac2007-03-03 15:34:27 -05001233fail:
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001234
1235-------------------------------------------------
1236$ git commit
1237file.txt: needs merge
1238-------------------------------------------------
1239
Dan McGee5162e692007-12-29 00:20:38 -06001240Also, linkgit:git-status[1] will list those files as "unmerged", and the
J. Bruce Fieldsef561ac2007-03-03 15:34:27 -05001241files with conflicts will have conflict markers added, like this:
1242
1243-------------------------------------------------
1244<<<<<<< HEAD:file.txt
1245Hello world
1246=======
1247Goodbye
1248>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
1249-------------------------------------------------
1250
1251All 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
1258Note that the commit message will already be filled in for you with
1259some information about the merge. Normally you can just use this
1260default message unchanged, but you may add additional commentary of
1261your own if desired.
1262
Thomas Ackermann2de9b712013-01-21 20:17:53 +01001263The above is all you need to know to resolve a simple merge. But Git
J. Bruce Fieldsef561ac2007-03-03 15:34:27 -05001264also provides more information to help resolve conflicts:
1265
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04001266[[conflict-resolution]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02001267==== Getting conflict-resolution help during a merge
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001268
Thomas Ackermann2de9b712013-01-21 20:17:53 +01001269All of the changes that Git was able to merge automatically are
Dan McGee5162e692007-12-29 00:20:38 -06001270already added to the index file, so linkgit:git-diff[1] shows only
J. Bruce Fieldsef561ac2007-03-03 15:34:27 -05001271the conflicts. It uses an unusual syntax:
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001272
1273-------------------------------------------------
1274$ git diff
1275diff --cc file.txt
1276index 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 Hamano11308452007-07-24 01:58:51 -07001287Recall that the commit which will be committed after we resolve this
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001288conflict will have two parents instead of the usual one: one parent
1289will be HEAD, the tip of the current branch; the other will be the
1290tip of the other branch, which is stored temporarily in MERGE_HEAD.
1291
J. Bruce Fieldsef561ac2007-03-03 15:34:27 -05001292During the merge, the index holds three versions of each file. Each of
1293these 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 Hamano42097522008-06-12 14:30:37 -07001297$ git show :2:file.txt # the version from HEAD.
1298$ git show :3:file.txt # the version from MERGE_HEAD.
J. Bruce Fieldsef561ac2007-03-03 15:34:27 -05001299-------------------------------------------------
1300
Junio C Hamano42097522008-06-12 14:30:37 -07001301When you ask linkgit:git-diff[1] to show the conflicts, it runs a
1302three-way diff between the conflicted merge results in the work tree with
1303stages 2 and 3 to show only hunks whose contents come from both sides,
1304mixed (in other words, when a hunk's merge results come only from stage 2,
1305that part is not conflicting and is not shown. Same for stage 3).
J. Bruce Fieldsef561ac2007-03-03 15:34:27 -05001306
1307The diff above shows the differences between the working-tree version of
1308file.txt and the stage 2 and stage 3 versions. So instead of preceding
W. Trevor King1249d8a2013-02-25 17:53:00 -05001309each line by a single `+` or `-`, it now uses two columns: the first
J. Bruce Fieldsef561ac2007-03-03 15:34:27 -05001310column is used for differences between the first parent and the working
1311directory copy, and the second for differences between the second parent
1312and the working directory copy. (See the "COMBINED DIFF FORMAT" section
Dan McGee5162e692007-12-29 00:20:38 -06001313of linkgit:git-diff-files[1] for a details of the format.)
J. Bruce Fieldsef561ac2007-03-03 15:34:27 -05001314
1315After resolving the conflict in the obvious way (but before updating the
1316index), the diff will look like:
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001317
1318-------------------------------------------------
1319$ git diff
1320diff --cc file.txt
1321index 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
1330This shows that our resolved version deleted "Hello world" from the
1331first parent, deleted "Goodbye" from the second parent, and added
1332"Goodbye world", which was previously absent from both.
1333
J. Bruce Fieldsef561ac2007-03-03 15:34:27 -05001334Some special diff options allow diffing the working directory against
1335any 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 Blain4fa1edb2023-05-22 19:29:00 +00001346When using the 'ort' merge strategy (the default), before updating the working
Junio C Hamanodada3862023-12-15 12:32:44 -08001347tree with the result of the merge, Git writes a ref named AUTO_MERGE
Philippe Blain4fa1edb2023-05-22 19:29:00 +00001348reflecting the state of the tree it is about to write. Conflicted paths with
1349textual conflicts that could not be automatically merged are written to this
1350tree with conflict markers, just as in the working tree. AUTO_MERGE can thus be
1351used with linkgit:git-diff[1] to show the changes you've made so far to resolve
1352conflicts. Using the same example as above, after resolving the conflict we
1353get:
1354
1355-------------------------------------------------
1356$ git diff AUTO_MERGE
1357diff --git a/file.txt b/file.txt
1358index 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
1370Notice that the diff shows we deleted the conflict markers and both versions of
1371the content line, and wrote "Goodbye world" instead.
1372
Jonathan Nieder0cafe942008-07-02 23:54:38 -05001373The linkgit:git-log[1] and linkgit:gitk[1] commands also provide special help
J. Bruce Fieldsef561ac2007-03-03 15:34:27 -05001374for merges:
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001375
1376-------------------------------------------------
1377$ git log --merge
J. Bruce Fieldsef561ac2007-03-03 15:34:27 -05001378$ gitk --merge
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001379-------------------------------------------------
1380
J. Bruce Fieldsef561ac2007-03-03 15:34:27 -05001381These will display all commits which exist only on HEAD or on
1382MERGE_HEAD, and which touch an unmerged file.
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001383
Dan McGee5162e692007-12-29 00:20:38 -06001384You may also use linkgit:git-mergetool[1], which lets you merge the
Henrik Austadc7719fb2009-01-05 16:25:36 +01001385unmerged files using external tools such as Emacs or kdiff3.
J. Bruce Fieldsc64415e2007-05-07 00:56:45 -04001386
J. Bruce Fieldsef561ac2007-03-03 15:34:27 -05001387Each time you resolve the conflicts in a file and update the index:
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001388
1389-------------------------------------------------
1390$ git add file.txt
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001391-------------------------------------------------
1392
J. Bruce Fieldsef561ac2007-03-03 15:34:27 -05001393the different stages of that file will be "collapsed", after which
Felipe Contreras6127c082009-04-04 12:38:23 +03001394`git diff` will (by default) no longer show diffs for that file.
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001395
1396[[undoing-a-merge]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02001397=== Undoing a merge
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001398
1399If you get stuck and decide to just give up and throw the whole mess
1400away, you can always return to the pre-merge state with
1401
1402-------------------------------------------------
Nguyễn Thái Ngọc Duyfc991b42019-04-25 16:45:57 +07001403$ git merge --abort
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001404-------------------------------------------------
1405
Junio C Hamano11308452007-07-24 01:58:51 -07001406Or, if you've already committed the merge that you want to throw away,
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001407
1408-------------------------------------------------
J. Bruce Fields1c73bb02007-02-19 18:46:09 -05001409$ git reset --hard ORIG_HEAD
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001410-------------------------------------------------
1411
1412However, this last command can be dangerous in some cases--never
1413throw away a commit you have already committed if that commit may
1414itself have been merged into another branch, as doing so may confuse
1415further merges.
1416
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04001417[[fast-forwards]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02001418=== Fast-forward merges
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001419
1420There is one special case not mentioned above, which is treated
1421differently. Normally, a merge results in a merge commit, with two
1422parents, one pointing at each of the two lines of development that
1423were merged.
1424
Xue Fuqiaob2af4822015-10-25 08:28:43 +08001425However, if the current branch is an ancestor of the other--so every commit
1426present in the current branch is already contained in the other branch--then Git
1427just performs a "fast-forward"; the head of the current branch is moved forward
1428to point at the head of the merged-in branch, without any new commits being
1429created.
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001430
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04001431[[fixing-mistakes]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02001432=== Fixing mistakes
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001433
1434If you've messed up the working tree, but haven't yet committed your
1435mistake, you can return the entire working tree to the last committed
1436state with
1437
1438-------------------------------------------------
Nguyễn Thái Ngọc Duy80f537f2019-04-25 16:45:58 +07001439$ git restore --staged --worktree :/
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001440-------------------------------------------------
1441
1442If you make a commit that you later wish you hadn't, there are two
1443fundamentally different ways to fix the problem:
1444
1445 1. You can create a new commit that undoes whatever was done
Sergei Organov93cbbd72007-11-14 12:08:15 -08001446 by the old commit. This is the correct thing if your
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001447 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 Ackermann2de9b712013-01-21 20:17:53 +01001451 Git does not normally expect the "history" of a project to
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001452 change, and cannot correctly perform repeated merges from
1453 a branch that has had its history changed.
1454
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04001455[[reverting-a-commit]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02001456==== Fixing a mistake with a new commit
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001457
1458Creating a new commit that reverts an earlier change is very easy;
Dan McGee5162e692007-12-29 00:20:38 -06001459just pass the linkgit:git-revert[1] command a reference to the bad
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001460commit; for example, to revert the most recent commit:
1461
1462-------------------------------------------------
1463$ git revert HEAD
1464-------------------------------------------------
1465
1466This will create a new commit which undoes the change in HEAD. You
1467will be given a chance to edit the commit message for the new commit.
1468
1469You can also revert an earlier change, for example, the next-to-last:
1470
1471-------------------------------------------------
1472$ git revert HEAD^
1473-------------------------------------------------
1474
Thomas Ackermann2de9b712013-01-21 20:17:53 +01001475In this case Git will attempt to undo the old change while leaving
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001476intact any changes made since then. If more recent changes overlap
1477with the changes to be reverted, then you will be asked to fix
1478conflicts manually, just as in the case of <<resolving-a-merge,
1479resolving a merge>>.
1480
J. Bruce Fields7cb192e2007-11-25 19:01:57 -05001481[[fixing-a-mistake-by-rewriting-history]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02001482==== Fixing a mistake by rewriting history
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001483
1484If the problematic commit is the most recent commit, and you have not
1485yet made that commit public, then you may just
Felipe Contreras6127c082009-04-04 12:38:23 +03001486<<undoing-a-merge,destroy it using `git reset`>>.
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001487
1488Alternatively, you
1489can edit the working directory and update the index to fix your
1490mistake, just as if you were going to <<how-to-make-a-commit,create a
1491new commit>>, then run
1492
1493-------------------------------------------------
1494$ git commit --amend
1495-------------------------------------------------
1496
1497which will replace the old commit by a new commit incorporating your
1498changes, giving you a chance to edit the old commit message first.
1499
1500Again, you should never do this to a commit that may already have
Dan McGee5162e692007-12-29 00:20:38 -06001501been merged into another branch; use linkgit:git-revert[1] instead in
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001502that case.
1503
J. Bruce Fields7cb192e2007-11-25 19:01:57 -05001504It is also possible to replace commits further back in the history, but
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001505this is an advanced topic to be left for
1506<<cleaning-up-history,another chapter>>.
1507
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04001508[[checkout-of-path]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02001509==== Checking out an old version of a file
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001510
1511In the process of undoing a previous bad change, you may find it
1512useful to check out an older version of a particular file using
Nguyễn Thái Ngọc Duy80f537f2019-04-25 16:45:58 +07001513linkgit:git-restore[1]. The command
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001514
1515-------------------------------------------------
Nguyễn Thái Ngọc Duy80f537f2019-04-25 16:45:58 +07001516$ git restore --source=HEAD^ path/to/file
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001517-------------------------------------------------
1518
1519replaces path/to/file by the contents it had in the commit HEAD^, and
1520also updates the index to match. It does not change branches.
1521
1522If you just want to look at an old version of the file, without
1523modifying the working directory, you can do that with
Dan McGee5162e692007-12-29 00:20:38 -06001524linkgit:git-show[1]:
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001525
1526-------------------------------------------------
J. Bruce Fieldsed4eb0d2007-03-10 22:00:12 -05001527$ git show HEAD^:path/to/file
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05001528-------------------------------------------------
1529
1530which will display the given version of the file.
1531
Junio C Hamano7a7cc592007-08-03 15:22:59 -07001532[[interrupted-work]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02001533==== Temporarily setting aside work in progress
Junio C Hamano7a7cc592007-08-03 15:22:59 -07001534
1535While you are in the middle of working on something complicated, you
1536find an unrelated but obvious and trivial bug. You would like to fix it
Dan McGee5162e692007-12-29 00:20:38 -06001537before continuing. You can use linkgit:git-stash[1] to save the current
Junio C Hamano7a7cc592007-08-03 15:22:59 -07001538state of your work, and after fixing the bug (or, optionally after doing
1539so on a different branch and then coming back), unstash the
1540work-in-progress changes.
1541
1542------------------------------------------------
Thomas Gummererdb377452017-10-22 18:04:07 +01001543$ git stash push -m "work in progress for foo feature"
Junio C Hamano7a7cc592007-08-03 15:22:59 -07001544------------------------------------------------
1545
1546This command will save your changes away to the `stash`, and
1547reset your working tree and the index to match the tip of your
1548current branch. Then you can make your fix as usual.
1549
1550------------------------------------------------
1551... edit and test ...
1552$ git commit -a -m "blorpl: typofix"
1553------------------------------------------------
1554
1555After that, you can go back to what you were working on with
Thomas Rast7b8988e2009-05-28 11:40:15 +02001556`git stash pop`:
Junio C Hamano7a7cc592007-08-03 15:22:59 -07001557
1558------------------------------------------------
Thomas Rast7b8988e2009-05-28 11:40:15 +02001559$ git stash pop
Junio C Hamano7a7cc592007-08-03 15:22:59 -07001560------------------------------------------------
1561
1562
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04001563[[ensuring-good-performance]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02001564=== Ensuring good performance
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001565
Thomas Ackermann2de9b712013-01-21 20:17:53 +01001566On large repositories, Git depends on compression to keep the history
W. Trevor King901fd182013-02-10 10:10:27 -05001567information from taking up too much space on disk or in memory. Some
Junio C Hamanoe1ebf212013-02-10 20:40:44 -08001568Git commands may automatically run linkgit:git-gc[1], so you don't
W. Trevor King901fd182013-02-10 10:10:27 -05001569have to worry about running it manually. However, compressing a large
1570repository may take a while, so you may want to call `gc` explicitly
1571to avoid automatic compression kicking in when it is not convenient.
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001572
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04001573
1574[[ensuring-reliability]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02001575=== Ensuring reliability
J. Bruce Fields11e016a2007-01-26 00:17:12 -05001576
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04001577[[checking-for-corruption]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02001578==== Checking the repository for corruption
J. Bruce Fields11e016a2007-01-26 00:17:12 -05001579
Dan McGee5162e692007-12-29 00:20:38 -06001580The linkgit:git-fsck[1] command runs a number of self-consistency checks
J. Bruce Fields1191ee12007-01-29 01:33:55 -05001581on the repository, and reports on any problems. This may take some
Junio C Hamanoc6a13b22012-02-28 14:55:39 -08001582time.
J. Bruce Fields21dcb3b2007-01-28 23:29:19 -05001583
1584-------------------------------------------------
J. Bruce Fields04e50e92007-01-28 23:31:47 -05001585$ git fsck
J. Bruce Fields21dcb3b2007-01-28 23:29:19 -05001586dangling commit 7281251ddd2a61e38657c827739c57015671a6b3
1587dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a63
1588dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b5
1589dangling blob 218761f9d90712d37a9c5e36f406f92202db07eb
1590dangling commit bf093535a34a4d35731aa2bd90fe6b176302f14f
1591dangling commit 8e4bec7f2ddaa268bef999853c25755452100f8e
1592dangling tree d50bb86186bf27b681d25af89d3b5b68382e4085
1593dangling tree b24c2473f1fd3d91352a624795be026d64c8841f
1594...
1595-------------------------------------------------
1596
Junio C Hamanoc6a13b22012-02-28 14:55:39 -08001597You will see informational messages on dangling objects. They are objects
1598that still exist in the repository but are no longer referenced by any of
W. Trevor King1249d8a2013-02-25 17:53:00 -05001599your branches, and can (and will) be removed after a while with `gc`.
Miklos Vajnab4ab1982012-06-19 19:56:09 +02001600You can run `git fsck --no-dangling` to suppress these messages, and still
Junio C Hamanoc6a13b22012-02-28 14:55:39 -08001601view real errors.
J. Bruce Fields1cdade22007-03-03 22:53:37 -05001602
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04001603[[recovering-lost-changes]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02001604==== Recovering lost changes
J. Bruce Fields11e016a2007-01-26 00:17:12 -05001605
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04001606[[reflogs]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02001607===== Reflogs
J. Bruce Fields559e4d72007-01-29 01:31:35 -05001608
W. Trevor King1249d8a2013-02-25 17:53:00 -05001609Say you modify a branch with <<fixing-mistakes,`git reset --hard`>>,
1610and then realize that the branch was the only reference you had to
1611that point in history.
J. Bruce Fields559e4d72007-01-29 01:31:35 -05001612
Thomas Ackermann2de9b712013-01-21 20:17:53 +01001613Fortunately, Git also keeps a log, called a "reflog", of all the
J. Bruce Fields559e4d72007-01-29 01:31:35 -05001614previous values of each branch. So in this case you can still find the
Junio C Hamanoa6080a02007-06-07 00:04:01 -07001615old history using, for example,
J. Bruce Fields559e4d72007-01-29 01:31:35 -05001616
1617-------------------------------------------------
1618$ git log master@{1}
1619-------------------------------------------------
1620
Sergei Organove502c2c2007-11-16 14:28:57 +03001621This lists the commits reachable from the previous version of the
W. Trevor King1249d8a2013-02-25 17:53:00 -05001622`master` branch head. This syntax can be used with any Git command
1623that accepts a commit, not just with `git log`. Some other examples:
J. Bruce Fields559e4d72007-01-29 01:31:35 -05001624
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 Fields953f3d62007-04-18 00:20:46 -04001630$ git log --walk-reflogs master # show reflog entries for master
J. Bruce Fields559e4d72007-01-29 01:31:35 -05001631-------------------------------------------------
1632
J. Bruce Fields953f3d62007-04-18 00:20:46 -04001633A separate reflog is kept for the HEAD, so
1634
1635-------------------------------------------------
1636$ git show HEAD@{"1 week ago"}
1637-------------------------------------------------
1638
1639will show what HEAD pointed to one week ago, not what the current branch
1640pointed to one week ago. This allows you to see the history of what
1641you've checked out.
1642
J. Bruce Fields559e4d72007-01-29 01:31:35 -05001643The reflogs are kept by default for 30 days, after which they may be
Dan McGee5162e692007-12-29 00:20:38 -06001644pruned. See linkgit:git-reflog[1] and linkgit:git-gc[1] to learn
J. Bruce Fields559e4d72007-01-29 01:31:35 -05001645how to control this pruning, and see the "SPECIFYING REVISIONS"
Jonathan Nieder9d83e382010-10-11 11:03:32 -05001646section of linkgit:gitrevisions[7] for details.
J. Bruce Fields559e4d72007-01-29 01:31:35 -05001647
Thomas Ackermann2de9b712013-01-21 20:17:53 +01001648Note that the reflog history is very different from normal Git history.
J. Bruce Fields559e4d72007-01-29 01:31:35 -05001649While normal history is shared by every repository that works on the
1650same project, the reflog history is not shared: it tells you only about
1651how the branches in your local repository have changed over time.
1652
J. Bruce Fields59723042007-04-30 11:11:02 -04001653[[dangling-object-recovery]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02001654===== Examining dangling objects
J. Bruce Fields559e4d72007-01-29 01:31:35 -05001655
J. Bruce Fields59723042007-04-30 11:11:02 -04001656In some situations the reflog may not be able to save you. For example,
1657suppose you delete a branch, then realize you need the history it
1658contained. The reflog is also deleted; however, if you have not yet
1659pruned the repository, then you may still be able to find the lost
Felipe Contreras6127c082009-04-04 12:38:23 +03001660commits in the dangling objects that `git fsck` reports. See
J. Bruce Fields59723042007-04-30 11:11:02 -04001661<<dangling-objects>> for the details.
J. Bruce Fields559e4d72007-01-29 01:31:35 -05001662
1663-------------------------------------------------
1664$ git fsck
1665dangling commit 7281251ddd2a61e38657c827739c57015671a6b3
1666dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a63
1667dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b5
1668...
1669-------------------------------------------------
1670
Mike Colemanaacd4042007-02-02 00:25:30 -06001671You can examine
J. Bruce Fields559e4d72007-01-29 01:31:35 -05001672one of those dangling commits with, for example,
1673
1674------------------------------------------------
1675$ gitk 7281251ddd --not --all
1676------------------------------------------------
1677
1678which does what it sounds like: it says that you want to see the commit
1679history that is described by the dangling commit(s), but not the
1680history that is described by all your existing branches and tags. Thus
1681you 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 Coleman79c96c52007-02-27 22:13:09 -06001684and complex commit history that was dropped.)
J. Bruce Fields559e4d72007-01-29 01:31:35 -05001685
1686If you decide you want the history back, you can always create a new
1687reference pointing to it, for example, a new branch:
1688
1689------------------------------------------------
Junio C Hamanoa6080a02007-06-07 00:04:01 -07001690$ git branch recovered-branch 7281251ddd
J. Bruce Fields559e4d72007-01-29 01:31:35 -05001691------------------------------------------------
1692
J. Bruce Fields59723042007-04-30 11:11:02 -04001693Other types of dangling objects (blobs and trees) are also possible, and
1694dangling objects can arise in other situations.
1695
J. Bruce Fields11e016a2007-01-26 00:17:12 -05001696
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04001697[[sharing-development]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02001698== Sharing development with others
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001699
Junio C Hamanoaa971cb2008-12-07 18:38:46 -08001700[[getting-updates-With-git-pull]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02001701=== Getting updates with git pull
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001702
Matthieu Moye63ec002009-11-22 23:26:18 +01001703After you clone a repository and commit a few changes of your own, you
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001704may wish to check the original repository for updates and merge them
1705into your own work.
1706
Junio C Hamanoaa971cb2008-12-07 18:38:46 -08001707We have already seen <<Updating-a-repository-With-git-fetch,how to
Matthieu Moy0e615b22010-11-02 16:31:20 +01001708keep remote-tracking branches up to date>> with linkgit:git-fetch[1],
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001709and how to merge two branches. So you can merge in changes from the
1710original repository's master branch with:
1711
1712-------------------------------------------------
1713$ git fetch
1714$ git merge origin/master
1715-------------------------------------------------
1716
Dan McGee5162e692007-12-29 00:20:38 -06001717However, the linkgit:git-pull[1] command provides a way to do this in
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001718one step:
1719
1720-------------------------------------------------
1721$ git pull origin master
1722-------------------------------------------------
1723
W. Trevor King1249d8a2013-02-25 17:53:00 -05001724In fact, if you have `master` checked out, then this branch has been
1725configured by `git clone` to get changes from the HEAD branch of the
Matthieu Moy66a062a2010-11-02 22:06:20 +01001726origin repository. So often you can
J. Bruce Fields0eb4f7c2007-08-05 17:18:52 -04001727accomplish the above with just a simple
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001728
1729-------------------------------------------------
1730$ git pull
1731-------------------------------------------------
1732
Matthieu Moy66a062a2010-11-02 22:06:20 +01001733This command will fetch changes from the remote branches to your
1734remote-tracking branches `origin/*`, and merge the default branch into
1735the current branch.
1736
Matthieu Moy29b9a662010-11-02 16:31:24 +01001737More generally, a branch that is created from a remote-tracking branch
1738will pull
J. Bruce Fields0eb4f7c2007-08-05 17:18:52 -04001739by default from that branch. See the descriptions of the
W. Trevor King1249d8a2013-02-25 17:53:00 -05001740`branch.<name>.remote` and `branch.<name>.merge` options in
Dan McGee5162e692007-12-29 00:20:38 -06001741linkgit:git-config[1], and the discussion of the `--track` option in
1742linkgit:git-checkout[1], to learn how to control these defaults.
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001743
W. Trevor King1249d8a2013-02-25 17:53:00 -05001744In addition to saving you keystrokes, `git pull` also helps you by
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001745producing a default commit message documenting the branch and
1746repository that you pulled from.
1747
1748(But note that no such commit will be created in the case of a
Felipe Contrerasa75d7b52009-10-24 11:31:32 +03001749<<fast-forwards,fast-forward>>; instead, your branch will just be
Michael Coleman79c96c52007-02-27 22:13:09 -06001750updated to point to the latest commit from the upstream branch.)
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001751
W. Trevor King1249d8a2013-02-25 17:53:00 -05001752The `git pull` command can also be given `.` as the "remote" repository,
J. Bruce Fields1191ee12007-01-29 01:33:55 -05001753in which case it just merges in a branch from the current repository; so
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001754the commands
1755
1756-------------------------------------------------
1757$ git pull . branch
1758$ git merge branch
1759-------------------------------------------------
1760
Thomas Ackermanna7bdee12013-08-27 19:58:18 +02001761are roughly equivalent.
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001762
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04001763[[submitting-patches]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02001764=== Submitting patches to a project
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001765
1766If you just have a few changes, the simplest way to submit them may
1767just be to send them as patches in email:
1768
Dan McGee5162e692007-12-29 00:20:38 -06001769First, use linkgit:git-format-patch[1]; for example:
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001770
1771-------------------------------------------------
Junio C Hamanoeb6ae7f2007-01-10 18:11:53 -08001772$ git format-patch origin
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001773-------------------------------------------------
1774
1775will produce a numbered series of files in the current directory, one
W. Trevor King1249d8a2013-02-25 17:53:00 -05001776for each patch in the current branch but not in `origin/HEAD`.
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001777
Philip Oakleyd84cef12012-10-21 22:34:08 +01001778`git format-patch` can include an initial "cover letter". You can insert
1779commentary on individual patches after the three dash line which
1780`format-patch` places after the commit message but before the patch
1781itself. 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
1783manner.
1784
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001785You can then import these into your mail client and send them by
1786hand. However, if you have a lot to send at once, you may prefer to
Dan McGee5162e692007-12-29 00:20:38 -06001787use the linkgit:git-send-email[1] script to automate the process.
Jeremiah Mahler3c735e02014-05-27 19:23:32 -07001788Consult the mailing list for your project first to determine
1789their requirements for submitting patches.
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001790
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04001791[[importing-patches]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02001792=== Importing patches to a project
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001793
Dan McGee5162e692007-12-29 00:20:38 -06001794Git also provides a tool called linkgit:git-am[1] (am stands for
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001795"apply mailbox"), for importing such an emailed series of patches.
1796Just save all of the patch-containing messages, in order, into a
W. Trevor King1249d8a2013-02-25 17:53:00 -05001797single mailbox file, say `patches.mbox`, then run
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001798
1799-------------------------------------------------
Junio C Hamanoeb6ae7f2007-01-10 18:11:53 -08001800$ git am -3 patches.mbox
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001801-------------------------------------------------
1802
1803Git will apply each patch in order; if any conflicts are found, it
1804will stop, and you can fix the conflicts as described in
W. Trevor King1249d8a2013-02-25 17:53:00 -05001805"<<resolving-a-merge,Resolving a merge>>". (The `-3` option tells
Thomas Ackermann2de9b712013-01-21 20:17:53 +01001806Git to perform a merge; if you would prefer it just to abort and
J. Bruce Fields01997b42007-01-10 23:23:37 -05001807leave your tree and index untouched, you may omit that option.)
1808
1809Once the index is updated with the results of the conflict
1810resolution, instead of creating a new commit, just run
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001811
1812-------------------------------------------------
Kevin Bracey8ceb6fb2013-06-26 23:06:41 +03001813$ git am --continue
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001814-------------------------------------------------
1815
Thomas Ackermann2de9b712013-01-21 20:17:53 +01001816and Git will create the commit for you and continue applying the
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001817remaining patches from the mailbox.
1818
1819The final result will be a series of commits, one for each patch in
1820the original mailbox, with authorship and commit log message each
1821taken from the message containing each patch.
1822
J. Bruce Fieldseda69442007-05-15 00:00:29 -04001823[[public-repositories]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02001824=== Public Git repositories
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001825
David Kastrup6e30fb02007-08-08 17:34:28 +02001826Another way to submit changes to a project is to tell the maintainer
1827of that project to pull the changes from your repository using
Junio C Hamanoaa971cb2008-12-07 18:38:46 -08001828linkgit:git-pull[1]. In the section "<<getting-updates-With-git-pull,
Felipe Contreras6127c082009-04-04 12:38:23 +03001829Getting updates with `git pull`>>" we described this as a way to get
David Kastrup6e30fb02007-08-08 17:34:28 +02001830updates from the "main" repository, but it works just as well in the
1831other direction.
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001832
J. Bruce Fieldseda69442007-05-15 00:00:29 -04001833If you and the maintainer both have accounts on the same machine, then
1834you can just pull changes from each other's repositories directly;
J. Bruce Fields11d51532007-06-18 16:38:22 -04001835commands that accept repository URLs as arguments will also accept a
J. Bruce Fieldseda69442007-05-15 00:00:29 -04001836local directory name:
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001837
1838-------------------------------------------------
1839$ git clone /path/to/repository
1840$ git pull /path/to/other/repository
1841-------------------------------------------------
1842
Ralf Wildenhuesc9016152007-10-09 23:03:55 +02001843or an ssh URL:
J. Bruce Fields11d51532007-06-18 16:38:22 -04001844
1845-------------------------------------------------
1846$ git clone ssh://yourhost/~you/repository
1847-------------------------------------------------
1848
1849For projects with few developers, or for synchronizing a few private
1850repositories, this may be all you need.
1851
J. Bruce Fieldseda69442007-05-15 00:00:29 -04001852However, the more common way to do this is to maintain a separate public
1853repository (usually on a different host) for others to pull changes
1854from. This is usually more convenient, and allows you to cleanly
1855separate private work in progress from publicly visible work.
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001856
1857You will continue to do your day-to-day work in your personal
1858repository, but periodically "push" changes from your personal
1859repository into your public repository, allowing other developers to
1860pull from that repository. So the flow of changes, in a situation
1861where there is one other developer with a public repository, looks
1862like this:
1863
Martin Ågrenc4d2f612019-09-22 13:57:59 +02001864....
1865 you push
1866your personal repo ------------------> your public repo
1867 ^ |
1868 | |
1869 | you pull | they pull
1870 | |
1871 | |
1872 | they push V
1873their public repo <------------------- their repo
1874....
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001875
J. Bruce Fields11d51532007-06-18 16:38:22 -04001876We explain how to do this in the following sections.
1877
J. Bruce Fieldseda69442007-05-15 00:00:29 -04001878[[setting-up-a-public-repository]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02001879==== Setting up a public repository
J. Bruce Fieldseda69442007-05-15 00:00:29 -04001880
W. Trevor King1249d8a2013-02-25 17:53:00 -05001881Assume your personal repository is in the directory `~/proj`. We
Felipe Contreras6127c082009-04-04 12:38:23 +03001882first create a new clone of the repository and tell `git daemon` that it
J. Bruce Fieldseda69442007-05-15 00:00:29 -04001883is meant to be public:
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001884
1885-------------------------------------------------
J. Bruce Fields52c80032007-05-07 23:34:26 -04001886$ git clone --bare ~/proj proj.git
J. Bruce Fieldseda69442007-05-15 00:00:29 -04001887$ touch proj.git/git-daemon-export-ok
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001888-------------------------------------------------
1889
J. Bruce Fields52c80032007-05-07 23:34:26 -04001890The resulting directory proj.git contains a "bare" git repository--it is
W. Trevor King1249d8a2013-02-25 17:53:00 -05001891just the contents of the `.git` directory, without any files checked out
J. Bruce Fieldseda69442007-05-15 00:00:29 -04001892around it.
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001893
W. Trevor King1249d8a2013-02-25 17:53:00 -05001894Next, copy `proj.git` to the server where you plan to host the
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001895public repository. You can use scp, rsync, or whatever is most
1896convenient.
1897
J. Bruce Fieldseda69442007-05-15 00:00:29 -04001898[[exporting-via-git]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02001899==== Exporting a Git repository via the Git protocol
J. Bruce Fieldseda69442007-05-15 00:00:29 -04001900
1901This is the preferred method.
1902
1903If someone else administers the server, they should tell you what
W. Trevor King1249d8a2013-02-25 17:53:00 -05001904directory to put the repository in, and what `git://` URL it will
1905appear at. You can then skip to the section
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001906"<<pushing-changes-to-a-public-repository,Pushing changes to a public
1907repository>>", below.
1908
Dan McGee5162e692007-12-29 00:20:38 -06001909Otherwise, all you need to do is start linkgit:git-daemon[1]; it will
J. Bruce Fieldseda69442007-05-15 00:00:29 -04001910listen on port 9418. By default, it will allow access to any directory
Thomas Ackermann2de9b712013-01-21 20:17:53 +01001911that looks like a Git directory and contains the magic file
Felipe Contreras6127c082009-04-04 12:38:23 +03001912git-daemon-export-ok. Passing some directory paths as `git daemon`
J. Bruce Fieldseda69442007-05-15 00:00:29 -04001913arguments will further restrict the exports to those paths.
1914
Felipe Contreras6127c082009-04-04 12:38:23 +03001915You can also run `git daemon` as an inetd service; see the
Dan McGee5162e692007-12-29 00:20:38 -06001916linkgit:git-daemon[1] man page for details. (See especially the
J. Bruce Fieldseda69442007-05-15 00:00:29 -04001917examples section.)
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001918
1919[[exporting-via-http]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02001920==== Exporting a git repository via HTTP
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001921
Thomas Ackermann2de9b712013-01-21 20:17:53 +01001922The Git protocol gives better performance and reliability, but on a
W. Trevor Kingde3f2c72013-02-10 10:10:37 -05001923host with a web server set up, HTTP exports may be simpler to set up.
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001924
Thomas Ackermann2de9b712013-01-21 20:17:53 +01001925All you need to do is place the newly created bare Git repository in
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001926a directory that is exported by the web server, and make some
1927adjustments 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 Fieldsc64415e2007-05-07 00:56:45 -04001932$ git --bare update-server-info
Petr Baudis7dce9912008-08-12 00:34:46 +02001933$ mv hooks/post-update.sample hooks/post-update
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001934-------------------------------------------------
1935
1936(For an explanation of the last two lines, see
Jonathan Nieder6998e4d2008-06-30 17:01:21 -05001937linkgit:git-update-server-info[1] and linkgit:githooks[5].)
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001938
W. Trevor King1249d8a2013-02-25 17:53:00 -05001939Advertise the URL of `proj.git`. Anybody else should then be able to
Ralf Wildenhuesc9016152007-10-09 23:03:55 +02001940clone or pull from that URL, for example with a command line like:
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001941
1942-------------------------------------------------
1943$ git clone http://yourserver.com/~you/proj.git
1944-------------------------------------------------
1945
1946(See also
Sebastian Schuberthd5ff3b42013-09-06 22:03:22 +02001947link:howto/setup-git-server-over-http.html[setup-git-server-over-http]
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001948for a slightly more sophisticated setup using WebDAV which also
W. Trevor Kingde3f2c72013-02-10 10:10:37 -05001949allows pushing over HTTP.)
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001950
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001951[[pushing-changes-to-a-public-repository]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02001952==== Pushing changes to a public repository
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001953
J. Bruce Fieldseda69442007-05-15 00:00:29 -04001954Note that the two techniques outlined above (exporting via
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001955<<exporting-via-http,http>> or <<exporting-via-git,git>>) allow other
1956maintainers to fetch your latest changes, but they do not allow write
1957access, which you will need to update the public repository with the
1958latest changes created in your private repository.
1959
Dan McGee5162e692007-12-29 00:20:38 -06001960The simplest way to do this is using linkgit:git-push[1] and ssh; to
W. Trevor King1249d8a2013-02-25 17:53:00 -05001961update the remote branch named `master` with the latest state of your
1962branch named `master`, run
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001963
1964-------------------------------------------------
1965$ git push ssh://yourserver.com/~you/proj.git master:master
1966-------------------------------------------------
1967
1968or just
1969
1970-------------------------------------------------
1971$ git push ssh://yourserver.com/~you/proj.git master
1972-------------------------------------------------
1973
Felipe Contreras6127c082009-04-04 12:38:23 +03001974As with `git fetch`, `git push` will complain if this does not result in a
Felipe Contrerasa75d7b52009-10-24 11:31:32 +03001975<<fast-forwards,fast-forward>>; see the following section for details on
J. Bruce Fields81eb4172007-11-25 17:54:19 -05001976handling this case.
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001977
W. Trevor King1249d8a2013-02-25 17:53:00 -05001978Note that the target of a `push` is normally a
J. Bruce Fields11d51532007-06-18 16:38:22 -04001979<<def_bare_repository,bare>> repository. You can also push to a
W. Trevor Kingd9be2482013-02-08 12:04:20 -05001980repository that has a checked-out working tree, but a push to update the
1981currently checked-out branch is denied by default to prevent confusion.
Junio C Hamano50995ed2013-02-18 12:43:00 -08001982See the description of the receive.denyCurrentBranch option
W. Trevor Kingd9be2482013-02-08 12:04:20 -05001983in linkgit:git-config[1] for details.
J. Bruce Fields11d51532007-06-18 16:38:22 -04001984
Felipe Contreras6127c082009-04-04 12:38:23 +03001985As with `git fetch`, you may also set up configuration options to
W. Trevor Kinge9b49082013-02-17 19:15:53 -05001986save typing; so, for example:
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001987
1988-------------------------------------------------
W. Trevor Kinge9b49082013-02-17 19:15:53 -05001989$ git remote add public-repo ssh://yourserver.com/~you/proj.git
1990-------------------------------------------------
1991
1992adds the following to `.git/config`:
1993
1994-------------------------------------------------
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001995[remote "public-repo"]
W. Trevor Kinge9b49082013-02-17 19:15:53 -05001996 url = yourserver.com:proj.git
1997 fetch = +refs/heads/*:refs/remotes/example/*
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05001998-------------------------------------------------
1999
W. Trevor Kinge9b49082013-02-17 19:15:53 -05002000which lets you do the same push with just
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05002001
2002-------------------------------------------------
2003$ git push public-repo master
2004-------------------------------------------------
2005
W. Trevor King1249d8a2013-02-25 17:53:00 -05002006See the explanations of the `remote.<name>.url`,
2007`branch.<name>.remote`, and `remote.<name>.push` options in
2008linkgit:git-config[1] for details.
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05002009
J. Bruce Fields81eb4172007-11-25 17:54:19 -05002010[[forcing-push]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02002011==== What to do when a push fails
J. Bruce Fields81eb4172007-11-25 17:54:19 -05002012
Felipe Contrerasa75d7b52009-10-24 11:31:32 +03002013If a push would not result in a <<fast-forwards,fast-forward>> of the
J. Bruce Fields81eb4172007-11-25 17:54:19 -05002014remote branch, then it will fail with an error like:
2015
2016-------------------------------------------------
Martin Ågren3c82eec2017-08-23 19:49:34 +02002017 ! [rejected] master -> master (non-fast-forward)
2018error: failed to push some refs to '...'
2019hint: Updates were rejected because the tip of your current branch is behind
2020hint: its remote counterpart. Integrate the remote changes (e.g.
2021hint: 'git pull ...') before pushing again.
2022hint: See the 'Note about fast-forwards' in 'git push --help' for details.
J. Bruce Fields81eb4172007-11-25 17:54:19 -05002023-------------------------------------------------
2024
2025This can happen, for example, if you:
2026
Felipe Contreras6127c082009-04-04 12:38:23 +03002027 - use `git reset --hard` to remove already-published commits, or
2028 - use `git commit --amend` to replace already-published commits
J. Bruce Fields7cb192e2007-11-25 19:01:57 -05002029 (as in <<fixing-a-mistake-by-rewriting-history>>), or
Felipe Contreras6127c082009-04-04 12:38:23 +03002030 - use `git rebase` to rebase any already-published commits (as
J. Bruce Fields81eb4172007-11-25 17:54:19 -05002031 in <<using-git-rebase>>).
2032
Felipe Contreras6127c082009-04-04 12:38:23 +03002033You may force `git push` to perform the update anyway by preceding the
J. Bruce Fields81eb4172007-11-25 17:54:19 -05002034branch name with a plus sign:
2035
2036-------------------------------------------------
2037$ git push ssh://yourserver.com/~you/proj.git +master
2038-------------------------------------------------
2039
W. Trevor Kingd1471e02013-02-17 19:15:55 -05002040Note 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 Fields81eb4172007-11-25 17:54:19 -05002047Normally whenever a branch head in a public repository is modified, it
Shawn Bohrer9e5d87d2007-12-12 22:36:21 -06002048is modified to point to a descendant of the commit that it pointed to
J. Bruce Fields81eb4172007-11-25 17:54:19 -05002049before. By forcing a push in this situation, you break that convention.
Junio C Hamanoaa971cb2008-12-07 18:38:46 -08002050(See <<problems-With-rewriting-history>>.)
J. Bruce Fields81eb4172007-11-25 17:54:19 -05002051
2052Nevertheless, this is a common practice for people that need a simple
2053way to publish a work-in-progress patch series, and it is an acceptable
2054compromise as long as you warn other developers that this is how you
2055intend to manage the branch.
2056
2057It's also possible for a push to fail in this way when other people have
2058the right to push to the same repository. In that case, the correct
Eric Hanchrow843c81d2008-07-08 13:00:30 -07002059solution is to retry the push after first updating your work: either by a
2060pull, or by a fetch followed by a rebase; see the
J. Bruce Fields81eb4172007-11-25 17:54:19 -05002061<<setting-up-a-shared-repository,next section>> and
Jonathan Nieder6998e4d2008-06-30 17:01:21 -05002062linkgit:gitcvs-migration[7] for more.
J. Bruce Fields81eb4172007-11-25 17:54:19 -05002063
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04002064[[setting-up-a-shared-repository]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02002065==== Setting up a shared repository
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05002066
2067Another way to collaborate is by using a model similar to that
2068commonly used in CVS, where several developers with special rights
2069all push to and pull from a single shared repository. See
Jonathan Nieder6998e4d2008-06-30 17:01:21 -05002070linkgit:gitcvs-migration[7] for instructions on how to
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05002071set this up.
2072
Thomas Ackermann2de9b712013-01-21 20:17:53 +01002073However, while there is nothing wrong with Git's support for shared
J. Bruce Fields8fae2222007-05-15 00:30:58 -04002074repositories, this mode of operation is not generally recommended,
Thomas Ackermann2de9b712013-01-21 20:17:53 +01002075simply because the mode of collaboration that Git supports--by
J. Bruce Fields8fae2222007-05-15 00:30:58 -04002076exchanging patches and pulling from public repositories--has so many
2077advantages 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 Contreras6127c082009-04-04 12:38:23 +03002081 high rates. And when that becomes too much, `git pull` provides
J. Bruce Fields8fae2222007-05-15 00:30:58 -04002082 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 Fieldse34caac2007-04-18 00:46:19 -04002094[[setting-up-gitweb]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02002095==== Allowing web browsing of a repository
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05002096
J. Bruce Fieldsa8cd1402007-01-30 12:43:36 -05002097The gitweb cgi script provides users an easy way to browse your
Stephen P. Smith99487cf2015-12-30 16:25:20 -07002098project's revisions, file contents and logs without having to install
2099Git. Features like RSS/Atom feeds and blame/annotation details may
2100optionally be enabled.
2101
2102The linkgit:git-instaweb[1] command provides a simple way to start
2103browsing the repository using gitweb. The default server when using
2104instaweb is lighttpd.
2105
2106See the file gitweb/INSTALL in the Git source tree and
Thomas Ackermannd285ab02016-03-03 19:43:51 +01002107linkgit:gitweb[1] for instructions on details setting up a permanent
Stephen P. Smith99487cf2015-12-30 16:25:20 -07002108installation with a CGI or Perl capable server.
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05002109
Stephen P. Smith9cfde9e2015-12-29 17:03:50 -07002110[[how-to-get-a-git-repository-with-minimal-history]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02002111=== How to get a Git repository with minimal history
Stephen P. Smith9cfde9e2015-12-29 17:03:50 -07002112
2113A <<def_shallow_clone,shallow clone>>, with its truncated
2114history, is useful when one is interested only in recent history
2115of a project and getting full history from the upstream is
2116expensive.
2117
2118A <<def_shallow_clone,shallow clone>> is created by specifying
2119the linkgit:git-clone[1] `--depth` switch. The depth can later be
2120changed with the linkgit:git-fetch[1] `--depth` switch, or full
2121history restored with `--unshallow`.
2122
2123Merging inside a <<def_shallow_clone,shallow clone>> will work as long
2124as a merge base is in the recent history.
2125Otherwise, it will be like merging unrelated histories and may
2126have to result in huge conflicts. This limitation may make such
2127a repository unsuitable to be used in merge based workflows.
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05002128
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04002129[[sharing-development-examples]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02002130=== Examples
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05002131
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002132[[maintaining-topic-branches]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02002133==== Maintaining topic branches for a Linux subsystem maintainer
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002134
Thomas Ackermann2de9b712013-01-21 20:17:53 +01002135This describes how Tony Luck uses Git in his role as maintainer of the
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002136IA64 architecture for the Linux kernel.
2137
2138He 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
2149He also uses a set of temporary branches ("topic branches"), each
2150containing a logical grouping of patches.
2151
2152To set this up, first create your work tree by cloning Linus's public
2153tree:
2154
2155-------------------------------------------------
W. Trevor King283efb02013-06-22 10:46:27 -04002156$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git work
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002157$ cd work
2158-------------------------------------------------
2159
Matthieu Moy29b9a662010-11-02 16:31:24 +01002160Linus's tree will be stored in the remote-tracking branch named origin/master,
Dan McGee5162e692007-12-29 00:20:38 -06002161and can be updated using linkgit:git-fetch[1]; you can track other
2162public trees using linkgit:git-remote[1] to set up a "remote" and
Martin Ågren7560f542017-08-23 19:49:35 +02002163linkgit:git-fetch[1] to keep them up to date; see
David Kastrup6e30fb02007-08-08 17:34:28 +02002164<<repositories-and-branches>>.
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002165
2166Now create the branches in which you are going to work; these start out
2167at the current tip of origin/master branch, and should be set up (using
W. Trevor King1249d8a2013-02-25 17:53:00 -05002168the `--track` option to linkgit:git-branch[1]) to merge changes in from
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002169Linus by default.
2170
2171-------------------------------------------------
2172$ git branch --track test origin/master
2173$ git branch --track release origin/master
2174-------------------------------------------------
2175
Dan McGee5162e692007-12-29 00:20:38 -06002176These can be easily kept up to date using linkgit:git-pull[1].
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002177
2178-------------------------------------------------
Nguyễn Thái Ngọc Duy328c6cb2019-03-29 17:39:19 +07002179$ git switch test && git pull
2180$ git switch release && git pull
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002181-------------------------------------------------
2182
2183Important note! If you have any local changes in these branches, then
2184this merge will create a commit object in the history (with no local
Thomas Ackermann2de9b712013-01-21 20:17:53 +01002185changes Git will simply do a "fast-forward" merge). Many people dislike
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002186the "noise" that this creates in the Linux history, so you should avoid
W. Trevor King1249d8a2013-02-25 17:53:00 -05002187doing this capriciously in the `release` branch, as these noisy commits
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002188will become part of the permanent history when you ask Linus to pull
2189from the release branch.
2190
Dan McGee5162e692007-12-29 00:20:38 -06002191A few configuration variables (see linkgit:git-config[1]) can
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002192make 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 King283efb02013-06-22 10:46:27 -04002198 url = master.kernel.org:/pub/scm/linux/kernel/git/aegl/linux.git
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002199 push = release
2200 push = test
2201EOF
2202-------------------------------------------------
2203
2204Then you can push both the test and release trees using
Dan McGee5162e692007-12-29 00:20:38 -06002205linkgit:git-push[1]:
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002206
2207-------------------------------------------------
2208$ git push mytree
2209-------------------------------------------------
2210
2211or push just one of the test and release branches using:
2212
2213-------------------------------------------------
2214$ git push mytree test
2215-------------------------------------------------
2216
2217or
2218
2219-------------------------------------------------
2220$ git push mytree release
2221-------------------------------------------------
2222
2223Now to apply some patches from the community. Think of a short
2224snappy name for a branch to hold this patch (or related group of
Luck, Tony352953a2010-10-01 11:57:52 -07002225patches), and create a new branch from a recent stable tag of
2226Linus's branch. Picking a stable base for your branch will:
22271) help you: by avoiding inclusion of unrelated and perhaps lightly
2228tested changes
W. Trevor King1249d8a2013-02-25 17:53:00 -050022292) help future bug hunters that use `git bisect` to find problems
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002230
2231-------------------------------------------------
Nguyễn Thái Ngọc Duy328c6cb2019-03-29 17:39:19 +07002232$ git switch -c speed-up-spinlocks v2.6.35
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002233-------------------------------------------------
2234
2235Now you apply the patch(es), run some tests, and commit the change(s). If
2236the patch is a multi-part series, then you should apply each as a separate
2237commit to this branch.
2238
2239-------------------------------------------------
2240$ ... patch ... test ... commit [ ... patch ... test ... commit ]*
2241-------------------------------------------------
2242
Thomas Ackermanna7bdee12013-08-27 19:58:18 +02002243When you are happy with the state of this change, you can merge it into the
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002244"test" branch in preparation to make it public:
2245
2246-------------------------------------------------
Nguyễn Thái Ngọc Duy328c6cb2019-03-29 17:39:19 +07002247$ git switch test && git merge speed-up-spinlocks
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002248-------------------------------------------------
2249
2250It is unlikely that you would have any conflicts here ... but you might if you
2251spent a while on this step and had also pulled new versions from upstream.
2252
Jeremiah Mahler3c735e02014-05-27 19:23:32 -07002253Sometime later when enough time has passed and testing done, you can pull the
W. Trevor King1249d8a2013-02-25 17:53:00 -05002254same branch into the `release` tree ready to go upstream. This is where you
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002255see the value of keeping each patch (or patch series) in its own branch. It
W. Trevor King1249d8a2013-02-25 17:53:00 -05002256means that the patches can be moved into the `release` tree in any order.
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002257
2258-------------------------------------------------
Nguyễn Thái Ngọc Duy328c6cb2019-03-29 17:39:19 +07002259$ git switch release && git merge speed-up-spinlocks
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002260-------------------------------------------------
2261
2262After a while, you will have a number of branches, and despite the
2263well chosen names you picked for each of them, you may forget what
2264they are for, or what status they are in. To get a reminder of what
2265changes are in a specific branch, use:
2266
2267-------------------------------------------------
Jonathan Nieder467c0192008-07-03 00:28:15 -05002268$ git log linux..branchname | git shortlog
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002269-------------------------------------------------
2270
Ralf Wildenhues06ada152007-10-09 23:00:03 +02002271To see whether it has already been merged into the test or release branches,
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002272use:
2273
2274-------------------------------------------------
2275$ git log test..branchname
2276-------------------------------------------------
2277
2278or
2279
2280-------------------------------------------------
2281$ git log release..branchname
2282-------------------------------------------------
2283
Ralf Wildenhues06ada152007-10-09 23:00:03 +02002284(If this branch has not yet been merged, you will see some log entries.
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002285If it has been merged, then there will be no output.)
2286
2287Once a patch completes the great cycle (moving from test to release,
2288then pulled by Linus, and finally coming back into your local
W. Trevor King1249d8a2013-02-25 17:53:00 -05002289`origin/master` branch), the branch for this change is no longer needed.
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002290You detect this when the output from:
2291
2292-------------------------------------------------
2293$ git log origin..branchname
2294-------------------------------------------------
2295
2296is empty. At this point the branch can be deleted:
2297
2298-------------------------------------------------
2299$ git branch -d branchname
2300-------------------------------------------------
2301
2302Some changes are so trivial that it is not necessary to create a separate
2303branch and then merge into each of the test and release branches. For
W. Trevor King1249d8a2013-02-25 17:53:00 -05002304these changes, just apply directly to the `release` branch, and then
2305merge that into the `test` branch.
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002306
W. Trevor Kingae6ef552013-02-19 05:05:01 -05002307After pushing your work to `mytree`, you can use
2308linkgit:git-request-pull[1] to prepare a "please pull" request message
2309to send to Linus:
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002310
2311-------------------------------------------------
W. Trevor Kingae6ef552013-02-19 05:05:01 -05002312$ git push mytree
2313$ git request-pull origin mytree release
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002314-------------------------------------------------
2315
2316Here are some of the scripts that simplify all this even further.
2317
2318-------------------------------------------------
2319==== update script ====
Thomas Ackermann48a8c262013-01-21 20:16:20 +01002320# Update a branch in my Git tree. If the branch to be updated
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002321# is origin, then pull from kernel.org. Otherwise merge
2322# origin/master branch into test|release branch
2323
2324case "$1" in
2325test|release)
2326 git checkout $1 && git pull . origin
2327 ;;
2328origin)
J. Bruce Fieldsfc74ecc2007-09-09 22:07:02 -04002329 before=$(git rev-parse refs/remotes/origin/master)
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002330 git fetch origin
J. Bruce Fieldsfc74ecc2007-09-09 22:07:02 -04002331 after=$(git rev-parse refs/remotes/origin/master)
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002332 if [ $before != $after ]
2333 then
2334 git log $before..$after | git shortlog
2335 fi
2336 ;;
2337*)
David Aguilar1a2ba8b2013-02-23 16:50:24 -08002338 echo "usage: $0 origin|test|release" 1>&2
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002339 exit 1
2340 ;;
2341esac
2342-------------------------------------------------
2343
2344-------------------------------------------------
2345==== merge script ====
2346# Merge a branch into either the test or release branch
2347
2348pname=$0
2349
2350usage()
2351{
David Aguilar1a2ba8b2013-02-23 16:50:24 -08002352 echo "usage: $pname branch test|release" 1>&2
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002353 exit 1
2354}
2355
J. Bruce Fieldsfc74ecc2007-09-09 22:07:02 -04002356git show-ref -q --verify -- refs/heads/"$1" || {
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002357 echo "Can't see branch <$1>" 1>&2
2358 usage
J. Bruce Fieldsfc74ecc2007-09-09 22:07:02 -04002359}
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002360
2361case "$2" in
2362test|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 ;;
2373esac
2374-------------------------------------------------
2375
2376-------------------------------------------------
2377==== status script ====
Thomas Ackermann48a8c262013-01-21 20:16:20 +01002378# report on status of my ia64 Git tree
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002379
2380gb=$(tput setab 2)
2381rb=$(tput setab 1)
2382restore=$(tput setab 9)
2383
2384if [ `git rev-list test..release | wc -c` -gt 0 ]
2385then
2386 echo $rb Warning: commits in release that are not in test $restore
2387 git log test..release
2388fi
2389
J. Bruce Fieldsfc74ecc2007-09-09 22:07:02 -04002390for branch in `git show-ref --heads | sed 's|^.*/||'`
J. Bruce Fields9e2163e2007-05-13 01:48:47 -04002391do
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
2424done
2425-------------------------------------------------
J. Bruce Fieldsb684f832007-01-08 23:42:36 -05002426
2427
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05002428[[cleaning-up-history]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02002429== Rewriting history and maintaining patch series
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05002430
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002431Normally commits are only added to a project, never taken away or
2432replaced. Git is designed with this assumption, and violating it will
Thomas Ackermann2de9b712013-01-21 20:17:53 +01002433cause Git's merge machinery (for example) to do the wrong thing.
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002434
2435However, there is a situation in which it can be useful to violate this
2436assumption.
2437
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04002438[[patch-series]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02002439=== Creating the perfect patch series
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002440
2441Suppose you are a contributor to a large project, and you want to add a
2442complicated feature, and to present it to the other developers in a way
2443that makes it easy for them to read your changes, verify that they are
2444correct, and understand why you made each change.
2445
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002446If you present all of your changes as a single patch (or commit), they
Michael Coleman79c96c52007-02-27 22:13:09 -06002447may find that it is too much to digest all at once.
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002448
2449If you present them with the entire history of your work, complete with
2450mistakes, corrections, and dead ends, they may be overwhelmed.
2451
2452So 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 Fieldsb181d572007-01-27 01:03:07 -05002466We will introduce some tools that can help you do this, explain how to
2467use them, and then explain some of the problems that can arise because
2468you are rewriting history.
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002469
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04002470[[using-git-rebase]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02002471=== Keeping a patch series up to date using git rebase
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002472
W. Trevor King1249d8a2013-02-25 17:53:00 -05002473Suppose that you create a branch `mywork` on a remote-tracking branch
2474`origin`, and create some commits on top of it:
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002475
2476-------------------------------------------------
Nguyễn Thái Ngọc Duy328c6cb2019-03-29 17:39:19 +07002477$ git switch -c mywork origin
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002478$ vi file.txt
2479$ git commit
2480$ vi otherfile.txt
2481$ git commit
2482...
2483-------------------------------------------------
2484
2485You have performed no merges into mywork, so it is just a simple linear
W. Trevor King1249d8a2013-02-25 17:53:00 -05002486sequence of patches on top of `origin`:
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002487
J. Bruce Fields1dc71a92007-03-10 22:38:13 -05002488................................................
Kirill Smelkovfa8347b2010-09-28 12:20:24 +04002489 o--o--O <-- origin
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002490 \
Kirill Smelkovfa8347b2010-09-28 12:20:24 +04002491 a--b--c <-- mywork
J. Bruce Fields1dc71a92007-03-10 22:38:13 -05002492................................................
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002493
2494Some more interesting work has been done in the upstream project, and
W. Trevor King1249d8a2013-02-25 17:53:00 -05002495`origin` has advanced:
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002496
J. Bruce Fields1dc71a92007-03-10 22:38:13 -05002497................................................
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002498 o--o--O--o--o--o <-- origin
2499 \
2500 a--b--c <-- mywork
J. Bruce Fields1dc71a92007-03-10 22:38:13 -05002501................................................
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002502
W. Trevor King1249d8a2013-02-25 17:53:00 -05002503At this point, you could use `pull` to merge your changes back in;
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002504the result would create a new merge commit, like this:
2505
J. Bruce Fields1dc71a92007-03-10 22:38:13 -05002506................................................
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002507 o--o--O--o--o--o <-- origin
2508 \ \
2509 a--b--c--m <-- mywork
J. Bruce Fields1dc71a92007-03-10 22:38:13 -05002510................................................
Junio C Hamanoa6080a02007-06-07 00:04:01 -07002511
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002512However, if you prefer to keep the history in mywork a simple series of
2513commits without any merges, you may instead choose to use
Dan McGee5162e692007-12-29 00:20:38 -06002514linkgit:git-rebase[1]:
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002515
2516-------------------------------------------------
Nguyễn Thái Ngọc Duy328c6cb2019-03-29 17:39:19 +07002517$ git switch mywork
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002518$ git rebase origin
2519-------------------------------------------------
2520
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002521This will remove each of your commits from mywork, temporarily saving
W. Trevor King1249d8a2013-02-25 17:53:00 -05002522them as patches (in a directory named `.git/rebase-apply`), update mywork to
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002523point at the latest version of origin, then apply each of the saved
2524patches to the new mywork. The result will look like:
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002525
2526
J. Bruce Fields1dc71a92007-03-10 22:38:13 -05002527................................................
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002528 o--o--O--o--o--o <-- origin
2529 \
2530 a'--b'--c' <-- mywork
J. Bruce Fields1dc71a92007-03-10 22:38:13 -05002531................................................
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002532
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002533In the process, it may discover conflicts. In that case it will stop
Felipe Contreras6127c082009-04-04 12:38:23 +03002534and allow you to fix the conflicts; after fixing conflicts, use `git add`
Jonathan Nieder7a7d4ef2008-07-03 00:20:21 -05002535to update the index with those contents, and then, instead of
Felipe Contreras6127c082009-04-04 12:38:23 +03002536running `git commit`, just run
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002537
2538-------------------------------------------------
2539$ git rebase --continue
2540-------------------------------------------------
2541
Thomas Ackermann2de9b712013-01-21 20:17:53 +01002542and Git will continue applying the rest of the patches.
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002543
Ralf Wildenhuesb6cbca32007-10-09 23:03:11 +02002544At any point you may use the `--abort` option to abort this process and
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002545return mywork to the state it had before you started the rebase:
2546
2547-------------------------------------------------
2548$ git rebase --abort
2549-------------------------------------------------
2550
W. Trevor King6c26bf42013-02-19 05:05:00 -05002551If you need to reorder or edit a number of commits in a branch, it may
2552be easier to use `git rebase -i`, which allows you to reorder and
2553squash commits, as well as marking them for individual editing during
2554the rebase. See <<interactive-rebase>> for details, and
2555<<reordering-patch-series>> for alternatives.
2556
J. Bruce Fields7cb192e2007-11-25 19:01:57 -05002557[[rewriting-one-commit]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02002558=== Rewriting a single commit
J. Bruce Fields365aa192007-03-03 14:30:32 -05002559
J. Bruce Fields7cb192e2007-11-25 19:01:57 -05002560We saw in <<fixing-a-mistake-by-rewriting-history>> that you can replace the
J. Bruce Fields365aa192007-03-03 14:30:32 -05002561most recent commit using
2562
2563-------------------------------------------------
2564$ git commit --amend
2565-------------------------------------------------
2566
2567which will replace the old commit by a new commit incorporating your
2568changes, giving you a chance to edit the old commit message first.
W. Trevor King6c26bf42013-02-19 05:05:00 -05002569This is useful for fixing typos in your last commit, or for adjusting
2570the patch contents of a poorly staged commit.
J. Bruce Fields365aa192007-03-03 14:30:32 -05002571
W. Trevor King6c26bf42013-02-19 05:05:00 -05002572If you need to amend commits from deeper in your history, you can
2573use <<interactive-rebase,interactive rebase's `edit` instruction>>.
J. Bruce Fields365aa192007-03-03 14:30:32 -05002574
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04002575[[reordering-patch-series]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02002576=== Reordering or selecting from a patch series
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002577
W. Trevor King6c26bf42013-02-19 05:05:00 -05002578Sometimes you want to edit a commit deeper in your history. One
2579approach is to use `git format-patch` to create a series of patches
2580and then reset the state to before the patches:
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002581
2582-------------------------------------------------
2583$ git format-patch origin
2584$ git reset --hard origin
2585-------------------------------------------------
2586
W. Trevor King6c26bf42013-02-19 05:05:00 -05002587Then modify, reorder, or eliminate patches as needed before applying
2588them again with linkgit:git-am[1]:
2589
2590-------------------------------------------------
2591$ git am *.patch
2592-------------------------------------------------
2593
2594[[interactive-rebase]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02002595=== Using interactive rebases
W. Trevor King6c26bf42013-02-19 05:05:00 -05002596
2597You can also edit a patch series with an interactive rebase. This is
2598the same as <<reordering-patch-series,reordering a patch series using
2599`format-patch`>>, so use whichever interface you like best.
2600
2601Rebase your current HEAD on the last commit you want to retain as-is.
2602For example, if you want to reorder the last 5 commits, use:
2603
2604-------------------------------------------------
2605$ git rebase -i HEAD~5
2606-------------------------------------------------
2607
2608This will open your editor with a list of steps to be taken to perform
2609your rebase.
2610
2611-------------------------------------------------
2612pick deadbee The oneline of this commit
2613pick 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
2635As explained in the comments, you can reorder commits, squash them
2636together, edit commit messages, etc. by editing the list. Once you
2637are satisfied, save the list and close your editor, and the rebase
2638will begin.
2639
2640The rebase will stop where `pick` has been replaced with `edit` or
2641when a step in the list fails to mechanically resolve conflicts and
2642needs your help. When you are done editing and/or resolving conflicts
2643you can continue with `git rebase --continue`. If you decide that
2644things are getting too hairy, you can always bail out with `git rebase
2645--abort`. Even after the rebase is complete, you can still recover
2646the original branch by using the <<reflogs,reflog>>.
2647
2648For a more detailed discussion of the procedure and additional tips,
2649see the "INTERACTIVE MODE" section of linkgit:git-rebase[1].
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002650
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04002651[[patch-series-tools]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02002652=== Other tools
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002653
Björn Gustavsson73a1d052009-11-22 10:47:04 +01002654There are numerous other tools, such as StGit, which exist for the
Michael Coleman79c96c52007-02-27 22:13:09 -06002655purpose of maintaining a patch series. These are outside of the scope of
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002656this manual.
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002657
Junio C Hamanoaa971cb2008-12-07 18:38:46 -08002658[[problems-With-rewriting-history]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02002659=== Problems with rewriting history
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002660
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002661The primary problem with rewriting the history of a branch has to do
2662with merging. Suppose somebody fetches your branch and merges it into
2663their branch, with a result something like this:
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002664
J. Bruce Fields1dc71a92007-03-10 22:38:13 -05002665................................................
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002666 o--o--O--o--o--o <-- origin
2667 \ \
2668 t--t--t--m <-- their branch:
J. Bruce Fields1dc71a92007-03-10 22:38:13 -05002669................................................
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002670
2671Then suppose you modify the last three commits:
2672
J. Bruce Fields1dc71a92007-03-10 22:38:13 -05002673................................................
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002674 o--o--o <-- new head of origin
2675 /
2676 o--o--O--o--o--o <-- old head of origin
J. Bruce Fields1dc71a92007-03-10 22:38:13 -05002677................................................
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002678
2679If we examined all this history together in one repository, it will
2680look like:
2681
J. Bruce Fields1dc71a92007-03-10 22:38:13 -05002682................................................
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002683 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 Fields1dc71a92007-03-10 22:38:13 -05002688................................................
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002689
2690Git has no way of knowing that the new head is an updated version of
2691the old head; it treats this situation exactly the same as it would if
2692two developers had independently done the work on the old and new heads
2693in parallel. At this point, if someone attempts to merge the new head
Thomas Ackermann2de9b712013-01-21 20:17:53 +01002694in to their branch, Git will attempt to merge together the two (old and
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002695new) lines of development, instead of trying to replace the old by the
2696new. The results are likely to be unexpected.
2697
2698You may still choose to publish branches whose history is rewritten,
2699and it may be useful for others to be able to fetch those branches in
2700order to examine or test them, but they should not attempt to pull such
2701branches into their own work.
2702
2703For true distributed development that supports proper merging,
2704published branches should never be rewritten.
2705
Steffen Prohaska3fb00282007-11-10 14:49:54 +01002706[[bisect-merges]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02002707=== Why bisecting merge commits can be harder than bisecting linear history
Steffen Prohaska3fb00282007-11-10 14:49:54 +01002708
Dan McGee5162e692007-12-29 00:20:38 -06002709The linkgit:git-bisect[1] command correctly handles history that
Steffen Prohaska3fb00282007-11-10 14:49:54 +01002710includes merge commits. However, when the commit that it finds is a
2711merge commit, the user may need to work harder than usual to figure out
2712why that commit introduced a problem.
2713
2714Imagine this history:
2715
2716................................................
2717 ---Z---o---X---...---o---A---C---D
2718 \ /
2719 o---o---Y---...---o---B
2720................................................
2721
2722Suppose that on the upper line of development, the meaning of one
2723of the functions that exists at Z is changed at commit X. The
2724commits from Z leading to A change both the function's
2725implementation and all calling sites that exist at Z, as well
2726as new calling sites they add, to be consistent. There is no
2727bug at A.
2728
2729Suppose that in the meantime on the lower line of development somebody
2730adds a new calling site for that function at commit Y. The
2731commits from Z leading to B all assume the old semantics of that
2732function and the callers and the callee are consistent with each
2733other. There is no bug at B, either.
2734
2735Suppose further that the two development lines merge cleanly at C,
2736so no conflict resolution is required.
2737
2738Nevertheless, the code at C is broken, because the callers added
2739on the lower line of development have not been converted to the new
2740semantics introduced on the upper line of development. So if all
2741you know is that D is bad, that Z is good, and that
Dan McGee5162e692007-12-29 00:20:38 -06002742linkgit:git-bisect[1] identifies C as the culprit, how will you
Steffen Prohaska3fb00282007-11-10 14:49:54 +01002743figure out that the problem is due to this change in semantics?
2744
Felipe Contreras6127c082009-04-04 12:38:23 +03002745When the result of a `git bisect` is a non-merge commit, you should
Steffen Prohaska3fb00282007-11-10 14:49:54 +01002746normally be able to discover the problem by examining just that commit.
2747Developers can make this easy by breaking their changes into small
2748self-contained commits. That won't help in the case above, however,
2749because the problem isn't obvious from examination of any single
2750commit; instead, a global view of the development is required. To
2751make matters worse, the change in semantics in the problematic
2752function may be just one small part of the changes in the upper
2753line of development.
2754
2755On the other hand, if instead of merging at C you had rebased the
2756history between Z to B on top of A, you would have gotten this
2757linear history:
2758
2759................................................................
2760 ---Z---o---X--...---o---A---o---o---Y*--...---o---B*--D*
2761................................................................
2762
2763Bisecting between Z and D* would hit a single culprit commit Y*,
2764and understanding why Y* was broken would probably be easier.
2765
Thomas Ackermann2de9b712013-01-21 20:17:53 +01002766Partly for this reason, many experienced Git users, even when
Steffen Prohaska3fb00282007-11-10 14:49:54 +01002767working on an otherwise merge-heavy project, keep the history
2768linear by rebasing against the latest upstream version before
2769publishing.
2770
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04002771[[advanced-branch-management]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02002772== Advanced branch management
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002773
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04002774[[fetching-individual-branches]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02002775=== Fetching individual branches
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002776
Dan McGee5162e692007-12-29 00:20:38 -06002777Instead of using linkgit:git-remote[1], you can also choose just
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002778to update one branch at a time, and to store it locally under an
2779arbitrary name:
2780
2781-------------------------------------------------
2782$ git fetch origin todo:my-todo-work
2783-------------------------------------------------
2784
W. Trevor King1249d8a2013-02-25 17:53:00 -05002785The first argument, `origin`, just tells Git to fetch from the
Thomas Ackermann2de9b712013-01-21 20:17:53 +01002786repository you originally cloned from. The second argument tells Git
W. Trevor King1249d8a2013-02-25 17:53:00 -05002787to fetch the branch named `todo` from the remote repository, and to
2788store it locally under the name `refs/heads/my-todo-work`.
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002789
2790You 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 King1249d8a2013-02-25 17:53:00 -05002796will create a new branch named `example-master` and store in it the
2797branch named `master` from the repository at the given URL. If you
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002798already have a branch named example-master, it will attempt to
J. Bruce Fields59723042007-04-30 11:11:02 -04002799<<fast-forwards,fast-forward>> to the commit given by example.com's
2800master branch. In more detail:
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002801
J. Bruce Fields59723042007-04-30 11:11:02 -04002802[[fetch-fast-forwards]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02002803=== git fetch and fast-forwards
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002804
W. Trevor King1249d8a2013-02-25 17:53:00 -05002805In the previous example, when updating an existing branch, `git fetch`
Jonathan Nieder7a7d4ef2008-07-03 00:20:21 -05002806checks to make sure that the most recent commit on the remote
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002807branch is a descendant of the most recent commit on your copy of the
2808branch before updating your copy of the branch to point at the new
Felipe Contrerasa75d7b52009-10-24 11:31:32 +03002809commit. Git calls this process a <<fast-forwards,fast-forward>>.
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002810
Felipe Contrerasa75d7b52009-10-24 11:31:32 +03002811A fast-forward looks something like this:
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002812
J. Bruce Fields1dc71a92007-03-10 22:38:13 -05002813................................................
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002814 o--o--o--o <-- old head of the branch
2815 \
2816 o--o--o <-- new head of the branch
J. Bruce Fields1dc71a92007-03-10 22:38:13 -05002817................................................
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002818
2819
2820In some cases it is possible that the new head will *not* actually be
2821a descendant of the old head. For example, the developer may have
Felipe Contreras69b33672021-06-15 14:11:09 +00002822realized a serious mistake was made and decided to backtrack,
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002823resulting in a situation like:
2824
J. Bruce Fields1dc71a92007-03-10 22:38:13 -05002825................................................
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002826 o--o--o--o--a--b <-- old head of the branch
2827 \
2828 o--o--o <-- new head of the branch
J. Bruce Fields1dc71a92007-03-10 22:38:13 -05002829................................................
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002830
W. Trevor King1249d8a2013-02-25 17:53:00 -05002831In this case, `git fetch` will fail, and print out a warning.
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002832
Thomas Ackermann2de9b712013-01-21 20:17:53 +01002833In that case, you can still force Git to update to the new head, as
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002834described in the following section. However, note that in the
W. Trevor King1249d8a2013-02-25 17:53:00 -05002835situation above this may mean losing the commits labeled `a` and `b`,
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002836unless you've already created a reference of your own pointing to
2837them.
2838
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04002839[[forcing-fetch]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02002840=== Forcing git fetch to do non-fast-forward updates
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002841
2842If git fetch fails because the new head of a branch is not a
2843descendant 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 King1249d8a2013-02-25 17:53:00 -05002849Note the addition of the `+` sign. Alternatively, you can use the `-f`
J. Bruce Fieldsc64415e2007-05-07 00:56:45 -04002850flag to force updates of all the fetched branches, as in:
2851
2852-------------------------------------------------
2853$ git fetch -f origin
2854-------------------------------------------------
2855
2856Be aware that commits that the old version of example/master pointed at
2857may be lost, as we saw in the previous section.
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002858
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04002859[[remote-branch-configuration]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02002860=== Configuring remote-tracking branches
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002861
W. Trevor King1249d8a2013-02-25 17:53:00 -05002862We saw above that `origin` is just a shortcut to refer to the
Michael Coleman79c96c52007-02-27 22:13:09 -06002863repository that you originally cloned from. This information is
Thomas Ackermann2de9b712013-01-21 20:17:53 +01002864stored in Git configuration variables, which you can see using
Dan McGee5162e692007-12-29 00:20:38 -06002865linkgit:git-config[1]:
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002866
2867-------------------------------------------------
J. Bruce Fields9d13bda2007-01-28 23:50:22 -05002868$ git config -l
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002869core.repositoryformatversion=0
2870core.filemode=true
2871core.logallrefupdates=true
2872remote.origin.url=git://git.kernel.org/pub/scm/git/git.git
2873remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
2874branch.master.remote=origin
2875branch.master.merge=refs/heads/master
2876-------------------------------------------------
2877
2878If there are other repositories that you also use frequently, you can
2879create similar configuration options to save typing; for example,
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002880
2881-------------------------------------------------
W. Trevor King47adb8a2013-02-17 19:15:56 -05002882$ git remote add example git://example.com/proj.git
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002883-------------------------------------------------
2884
W. Trevor King47adb8a2013-02-17 19:15:56 -05002885adds the following to `.git/config`:
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002886
2887-------------------------------------------------
W. Trevor King47adb8a2013-02-17 19:15:56 -05002888[remote "example"]
2889 url = git://example.com/proj.git
2890 fetch = +refs/heads/*:refs/remotes/example/*
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002891-------------------------------------------------
2892
W. Trevor King47adb8a2013-02-17 19:15:56 -05002893Also note that the above configuration can be performed by directly
2894editing the file `.git/config` instead of using linkgit:git-remote[1].
2895
2896After configuring the remote, the following three commands will do the
2897same thing:
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002898
2899-------------------------------------------------
W. Trevor King47adb8a2013-02-17 19:15:56 -05002900$ git fetch git://example.com/proj.git +refs/heads/*:refs/remotes/example/*
2901$ git fetch example +refs/heads/*:refs/remotes/example/*
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002902$ git fetch example
2903-------------------------------------------------
2904
Dan McGee5162e692007-12-29 00:20:38 -06002905See linkgit:git-config[1] for more details on the configuration
W. Trevor King47adb8a2013-02-17 19:15:56 -05002906options mentioned above and linkgit:git-fetch[1] for more details on
2907the refspec syntax.
J. Bruce Fields4c63ff42007-01-07 23:57:41 -05002908
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05002909
J. Bruce Fields036f8192007-08-30 23:10:05 -04002910[[git-concepts]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02002911== Git concepts
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05002912
J. Bruce Fields036f8192007-08-30 23:10:05 -04002913Git is built on a small number of simple but powerful ideas. While it
2914is possible to get things done without understanding them, you will find
Thomas Ackermann2de9b712013-01-21 20:17:53 +01002915Git much more intuitive if you do.
J. Bruce Fields036f8192007-08-30 23:10:05 -04002916
2917We start with the most important, the <<def_object_database,object
2918database>> and the <<def_index,index>>.
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002919
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04002920[[the-object-database]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02002921=== The Object Database
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002922
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002923
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04002924We already saw in <<understanding-commits>> that all commits are stored
2925under a 40-digit "object name". In fact, all the information needed to
2926represent the history of a project is stored in objects with such names.
Felipe Contrerasa6e5ef72009-04-04 12:38:27 +03002927In each case the name is calculated by taking the SHA-1 hash of the
2928contents of the object. The SHA-1 hash is a cryptographic hash function.
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04002929What that means to us is that it is impossible to find two different
2930objects with the same name. This has a number of advantages; among
2931others:
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002932
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04002933- Git can quickly determine whether two objects are identical or not,
2934 just by comparing names.
Ralf Wildenhues06ada152007-10-09 23:00:03 +02002935- Since object names are computed the same way in every repository, the
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04002936 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 Contrerasa6e5ef72009-04-04 12:38:27 +03002939 object's name is still the SHA-1 hash of its contents.
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002940
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04002941(See <<object-details>> for the details of the object formatting and
Felipe Contrerasa6e5ef72009-04-04 12:38:27 +03002942SHA-1 calculation.)
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002943
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04002944There are four different types of objects: "blob", "tree", "commit", and
2945"tag".
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002946
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04002947- A <<def_blob_object,"blob" object>> is used to store file data.
Eric Hanchrow843c81d2008-07-08 13:00:30 -07002948- A <<def_tree_object,"tree" object>> ties one or more
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04002949 "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 Wildenhues2ef8ac12007-10-09 23:05:30 +02002952 together into a <<def_DAG,directed acyclic graph>> of revisions--each
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04002953 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 Fieldsb181d572007-01-27 01:03:07 -05002961
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002962The object types in some more detail:
2963
J. Bruce Fields513d4192007-08-31 23:26:38 -04002964[[commit-object]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02002965==== Commit Object
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002966
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04002967The "commit" object links a physical state of a tree with a description
W. Trevor King1249d8a2013-02-25 17:53:00 -05002968of how we got there and why. Use the `--pretty=raw` option to
Dan McGee5162e692007-12-29 00:20:38 -06002969linkgit:git-show[1] or linkgit:git-log[1] to examine your favorite
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04002970commit:
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002971
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04002972------------------------------------------------
2973$ git show -s --pretty=raw 2be7fcb476
2974commit 2be7fcb4764f2dbcee52635b91fedb1b3dcf7ab4
2975tree fb3a8bdd0ceddd019615af4d57a53f43d8cee2bf
2976parent 257a84d9d02e90447b149af58b271c19405edb6a
2977author Dave Watson <dwatson@mimvista.com> 1187576872 -0400
2978committer Junio C Hamano <gitster@pobox.com> 1187591163 -0700
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05002979
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04002980 Fix misspelling of 'suppress' in docs
J. Bruce Fields513d4192007-08-31 23:26:38 -04002981
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04002982 Signed-off-by: Junio C Hamano <gitster@pobox.com>
2983------------------------------------------------
2984
2985As you can see, a commit is defined by:
2986
Felipe Contrerasa6e5ef72009-04-04 12:38:27 +03002987- a tree: The SHA-1 name of a tree object (as defined below), representing
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04002988 the contents of a directory at a certain point in time.
Štěpán Němecedfbbf72012-07-15 00:20:36 +02002989- parent(s): The SHA-1 name(s) of some number of commits which represent the
Shawn Bohrer9e5d87d2007-12-12 22:36:21 -06002990 immediately previous step(s) in the history of the project. The
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04002991 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
3004Note that a commit does not itself contain any information about what
3005actually changed; all changes are calculated by comparing the contents
3006of the tree referred to by this commit with the trees associated with
Thomas Ackermann2de9b712013-01-21 20:17:53 +01003007its parents. In particular, Git does not attempt to record file renames
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04003008explicitly, though it can identify cases where the existence of the same
3009file data at changing paths suggests a rename. (See, for example, the
W. Trevor King1249d8a2013-02-25 17:53:00 -05003010`-M` option to linkgit:git-diff[1]).
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04003011
Dan McGee5162e692007-12-29 00:20:38 -06003012A commit is usually created by linkgit:git-commit[1], which creates a
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04003013commit whose parent is normally the current HEAD, and whose tree is
3014taken from the content currently stored in the index.
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003015
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04003016[[tree-object]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02003017==== Tree Object
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003018
Dan McGee5162e692007-12-29 00:20:38 -06003019The ever-versatile linkgit:git-show[1] command can also be used to
3020examine tree objects, but linkgit:git-ls-tree[1] will give you more
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04003021details:
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003022
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04003023------------------------------------------------
3024$ git ls-tree fb3a8bdd0ce
3025100644 blob 63c918c667fa005ff12ad89437f2fdc80926e21c .gitignore
3026100644 blob 5529b198e8d14decbe4ad99db3f7fb632de0439d .mailmap
3027100644 blob 6ff87c4664981e4397625791c8ea3bbb5f2279a3 COPYING
3028040000 tree 2fb783e477100ce076f6bf57e4a6f026013dc745 Documentation
3029100755 blob 3c0032cec592a765692234f1cba47dfdcc3a9200 GIT-VERSION-GEN
3030100644 blob 289b046a443c0647624607d471289b2c7dcd470b INSTALL
3031100644 blob 4eb463797adc693dc168b926b6932ff53f17d0b1 Makefile
3032100644 blob 548142c327a6790ff8821d67c2ee1eff7a656b52 README
3033...
3034------------------------------------------------
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003035
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04003036As you can see, a tree object contains a list of entries, each with a
Felipe Contrerasa6e5ef72009-04-04 12:38:27 +03003037mode, object type, SHA-1 name, and name, sorted by name. It represents
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04003038the contents of a single directory tree.
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003039
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04003040The object type may be a blob, representing the contents of a file, or
3041another tree, representing the contents of a subdirectory. Since trees
Felipe Contrerasa6e5ef72009-04-04 12:38:27 +03003042and blobs, like all other objects, are named by the SHA-1 hash of their
3043contents, two trees have the same SHA-1 name if and only if their
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04003044contents (including, recursively, the contents of all subdirectories)
Thomas Ackermann2de9b712013-01-21 20:17:53 +01003045are identical. This allows Git to quickly determine the differences
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04003046between two related tree objects, since it can ignore any entries with
3047identical object names.
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003048
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04003049(Note: in the presence of submodules, trees may also have commits as
Michael Smith6dd14362007-09-25 08:44:38 -04003050entries. See <<submodules>> for documentation.)
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003051
Thomas Ackermann2de9b712013-01-21 20:17:53 +01003052Note that the files all have mode 644 or 755: Git actually only pays
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04003053attention to the executable bit.
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003054
J. Bruce Fields513d4192007-08-31 23:26:38 -04003055[[blob-object]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02003056==== Blob Object
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003057
Dan McGee5162e692007-12-29 00:20:38 -06003058You can use linkgit:git-show[1] to examine the contents of a blob; take,
W. Trevor King1249d8a2013-02-25 17:53:00 -05003059for example, the blob in the entry for `COPYING` from the tree above:
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003060
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04003061------------------------------------------------
3062$ git show 6ff87c4664
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003063
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04003064 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
3070A "blob" object is nothing but a binary blob of data. It doesn't refer
3071to anything else or have attributes of any kind.
3072
3073Since the blob is entirely defined by its data, if two files in a
3074directory tree (or in multiple different versions of the repository)
3075have the same contents, they will share the same blob object. The object
3076is totally independent of its location in the directory tree, and
3077renaming a file does not change the object that file is associated with.
3078
3079Note that any tree or blob object can be examined using
Dan McGee5162e692007-12-29 00:20:38 -06003080linkgit:git-show[1] with the <revision>:<path> syntax. This can
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04003081sometimes be useful for browsing the contents of a tree that is not
3082currently checked out.
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003083
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04003084[[trust]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02003085==== Trust
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003086
Felipe Contrerasa6e5ef72009-04-04 12:38:27 +03003087If you receive the SHA-1 name of a blob from one source, and its contents
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04003088from another (possibly untrusted) source, you can still trust that those
Felipe Contrerasa6e5ef72009-04-04 12:38:27 +03003089contents are correct as long as the SHA-1 name agrees. This is because
3090the SHA-1 is designed so that it is infeasible to find different contents
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04003091that produce the same hash.
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003092
Felipe Contrerasa6e5ef72009-04-04 12:38:27 +03003093Similarly, you need only trust the SHA-1 name of a top-level tree object
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04003094to trust the contents of the entire directory that it refers to, and if
Felipe Contrerasa6e5ef72009-04-04 12:38:27 +03003095you receive the SHA-1 name of a commit from a trusted source, then you
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04003096can easily verify the entire history of commits reachable through
3097parents of that commit, and all of those contents of the trees referred
3098to by those commits.
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003099
3100So to introduce some real trust in the system, the only thing you need
3101to do is to digitally sign just 'one' special note, which includes the
3102name of a top-level commit. Your digital signature shows others
3103that you trust that commit, and the immutability of the history of
3104commits tells others that they can trust the whole history.
3105
3106In other words, you can easily validate a whole archive by just
Felipe Contrerasa6e5ef72009-04-04 12:38:27 +03003107sending out a single email that tells the people the name (SHA-1 hash)
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003108of the top commit, and digitally sign that email using something
3109like GPG/PGP.
3110
Thomas Ackermann2de9b712013-01-21 20:17:53 +01003111To assist in this, Git also provides the tag object...
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003112
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04003113[[tag-object]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02003114==== Tag Object
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003115
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04003116A tag object contains an object, object type, tag name, the name of the
3117person ("tagger") who created the tag, and a message, which may contain
Eric Hanchrow843c81d2008-07-08 13:00:30 -07003118a signature, as can be seen using linkgit:git-cat-file[1]:
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003119
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04003120------------------------------------------------
3121$ git cat-file tag v1.5.0
3122object 437b1b20df4b356c9342dac8d38849f24ef44f27
3123type commit
3124tag v1.5.0
3125tagger Junio C Hamano <junkio@cox.net> 1171411200 +0000
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003126
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04003127GIT 1.5.0
3128-----BEGIN PGP SIGNATURE-----
3129Version: GnuPG v1.4.6 (GNU/Linux)
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003130
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04003131iD8DBQBF0lGqwMbZpPMRm5oRAuRiAJ9ohBLd7s2kqjkKlq1qqC57SbnmzQCdG4ui
3132nLE/L9aUXdWeTFPron96DLA=
3133=2E+0
3134-----END PGP SIGNATURE-----
3135------------------------------------------------
3136
Dan McGee5162e692007-12-29 00:20:38 -06003137See the linkgit:git-tag[1] command to learn how to create and verify tag
3138objects. (Note that linkgit:git-tag[1] can also be used to create
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04003139"lightweight tags", which are not tag objects at all, but just simple
W. Trevor King1249d8a2013-02-25 17:53:00 -05003140references whose names begin with `refs/tags/`).
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003141
J. Bruce Fields09eff7b2007-09-08 22:13:53 -04003142[[pack-files]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02003143==== How Git stores objects efficiently: pack files
J. Bruce Fields09eff7b2007-09-08 22:13:53 -04003144
J. Bruce Fields9644ffd2007-09-08 22:27:18 -04003145Newly created objects are initially created in a file named after the
W. Trevor King1249d8a2013-02-25 17:53:00 -05003146object's SHA-1 hash (stored in `.git/objects`).
J. Bruce Fields09eff7b2007-09-08 22:13:53 -04003147
3148Unfortunately this system becomes inefficient once a project has a
3149lot of objects. Try this on an old project:
3150
3151------------------------------------------------
3152$ git count-objects
31536930 objects, 47620 kilobytes
3154------------------------------------------------
3155
3156The first number is the number of objects which are kept in
3157individual files. The second is the amount of space taken up by
3158those "loose" objects.
3159
Thomas Ackermann2de9b712013-01-21 20:17:53 +01003160You can save space and make Git faster by moving these loose objects in
J. Bruce Fields09eff7b2007-09-08 22:13:53 -04003161to a "pack file", which stores a group of objects in an efficient
3162compressed format; the details of how pack files are formatted can be
Todd Zullinger086eaab2022-09-16 02:23:02 -04003163found in linkgit:gitformat-pack[5].
J. Bruce Fields09eff7b2007-09-08 22:13:53 -04003164
3165To put the loose objects into a pack, just run git repack:
3166
3167------------------------------------------------
3168$ git repack
Thomas Ackermann3e65ac42013-08-27 19:56:50 +02003169Counting objects: 6020, done.
3170Delta compression using up to 4 threads.
3171Compressing objects: 100% (6020/6020), done.
3172Writing objects: 100% (6020/6020), done.
3173Total 6020 (delta 4070), reused 0 (delta 0)
J. Bruce Fields09eff7b2007-09-08 22:13:53 -04003174------------------------------------------------
3175
Thomas Ackermann3e65ac42013-08-27 19:56:50 +02003176This creates a single "pack file" in .git/objects/pack/
3177containing all currently unpacked objects. You can then run
J. Bruce Fields09eff7b2007-09-08 22:13:53 -04003178
3179------------------------------------------------
3180$ git prune
3181------------------------------------------------
3182
3183to remove any of the "loose" objects that are now contained in the
3184pack. This will also remove any unreferenced objects (which may be
W. Trevor King1249d8a2013-02-25 17:53:00 -05003185created when, for example, you use `git reset` to remove a commit).
J. Bruce Fields09eff7b2007-09-08 22:13:53 -04003186You can verify that the loose objects are gone by looking at the
W. Trevor King1249d8a2013-02-25 17:53:00 -05003187`.git/objects` directory or by running
J. Bruce Fields09eff7b2007-09-08 22:13:53 -04003188
3189------------------------------------------------
3190$ git count-objects
31910 objects, 0 kilobytes
3192------------------------------------------------
3193
3194Although the object files are gone, any commands that refer to those
3195objects will work exactly as they did before.
3196
Dan McGee5162e692007-12-29 00:20:38 -06003197The linkgit:git-gc[1] command performs packing, pruning, and more for
J. Bruce Fields09eff7b2007-09-08 22:13:53 -04003198you, so is normally the only high-level command you need.
3199
3200[[dangling-objects]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02003201==== Dangling objects
J. Bruce Fields09eff7b2007-09-08 22:13:53 -04003202
Dan McGee5162e692007-12-29 00:20:38 -06003203The linkgit:git-fsck[1] command will sometimes complain about dangling
J. Bruce Fields09eff7b2007-09-08 22:13:53 -04003204objects. They are not a problem.
3205
3206The most common cause of dangling objects is that you've rebased a
3207branch, 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
3209branch still exists, as does everything it pointed to. The branch
3210pointer itself just doesn't, since you replaced it with another one.
3211
3212There are also other situations that cause dangling objects. For
W. Trevor King1249d8a2013-02-25 17:53:00 -05003213example, a "dangling blob" may arise because you did a `git add` of a
J. Bruce Fields09eff7b2007-09-08 22:13:53 -04003214file, but then, before you actually committed it and made it part of the
3215bigger picture, you changed something else in that file and committed
Ralf Wildenhues2ef8ac12007-10-09 23:05:30 +02003216that *updated* thing--the old state that you added originally ends up
J. Bruce Fields09eff7b2007-09-08 22:13:53 -04003217not being pointed to by any commit or tree, so it's now a dangling blob
3218object.
3219
Elijah Newrenf5a3c5e2021-08-04 05:38:02 +00003220Similarly, when the "ort" merge strategy runs, and finds that
J. Bruce Fields09eff7b2007-09-08 22:13:53 -04003221there are criss-cross merges and thus more than one merge base (which is
3222fairly unusual, but it does happen), it will generate one temporary
3223midway tree (or possibly even more, if you had lots of criss-crossing
3224merges and more than two merge bases) as a temporary internal merge
3225base, and again, those are real objects, but the end result will not end
3226up pointing to them, so they end up "dangling" in your repository.
3227
3228Generally, dangling objects aren't anything to worry about. They can
3229even be very useful: if you screw something up, the dangling objects can
3230be how you recover your old tree (say, you did a rebase, and realized
Ralf Wildenhues2ef8ac12007-10-09 23:05:30 +02003231that you really didn't want to--you can look at what dangling objects
J. Bruce Fields09eff7b2007-09-08 22:13:53 -04003232you have, and decide to reset your head to some old dangling state).
3233
3234For commits, you can just use:
3235
3236------------------------------------------------
3237$ gitk <dangling-commit-sha-goes-here> --not --all
3238------------------------------------------------
3239
3240This asks for all the history reachable from the given commit but not
3241from any branch, tag, or other reference. If you decide it's something
3242you 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
3248For blobs and trees, you can't do the same, but you can still examine
3249them. You can just do
3250
3251------------------------------------------------
3252$ git show <dangling-blob/tree-sha-goes-here>
3253------------------------------------------------
3254
3255to show what the contents of the blob were (or, for a tree, basically
W. Trevor King1249d8a2013-02-25 17:53:00 -05003256what the `ls` for that directory was), and that may give you some idea
J. Bruce Fields09eff7b2007-09-08 22:13:53 -04003257of what the operation was that left that dangling object.
3258
3259Usually, dangling blobs and trees aren't very interesting. They're
3260almost always the result of either being a half-way mergebase (the blob
3261will often even have the conflict markers from a merge in it, if you
3262have had conflicting merges that you fixed up by hand), or simply
W. Trevor King1249d8a2013-02-25 17:53:00 -05003263because you interrupted a `git fetch` with ^C or something like that,
J. Bruce Fields09eff7b2007-09-08 22:13:53 -04003264leaving _some_ of the new objects in the object database, but just
3265dangling and useless.
3266
3267Anyway, once you are sure that you're not interested in any dangling
3268state, you can just prune all unreachable objects:
3269
3270------------------------------------------------
3271$ git prune
3272------------------------------------------------
3273
Thomas Ackermannddeb8172013-08-27 20:05:50 +02003274and they'll be gone. (You should only run `git prune` on a quiescent
Ralf Wildenhues2ef8ac12007-10-09 23:05:30 +02003275repository--it's kind of like doing a filesystem fsck recovery: you
J. Bruce Fields09eff7b2007-09-08 22:13:53 -04003276don't want to do that while the filesystem is mounted.
Thomas Ackermannddeb8172013-08-27 20:05:50 +02003277`git prune` is designed not to cause any harm in such cases of concurrent
3278accesses to a repository but you might receive confusing or scary messages.)
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003279
J. Bruce Fields1cdade22007-03-03 22:53:37 -05003280[[recovering-from-repository-corruption]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02003281==== Recovering from repository corruption
J. Bruce Fields1cdade22007-03-03 22:53:37 -05003282
Thomas Ackermann2de9b712013-01-21 20:17:53 +01003283By design, Git treats data trusted to it with caution. However, even in
3284the absence of bugs in Git itself, it is still possible that hardware or
J. Bruce Fields1cdade22007-03-03 22:53:37 -05003285operating system errors could corrupt data.
3286
3287The first defense against such problems is backups. You can back up a
Thomas Ackermann2de9b712013-01-21 20:17:53 +01003288Git directory using clone, or just using cp, tar, or any other backup
J. Bruce Fields1cdade22007-03-03 22:53:37 -05003289mechanism.
3290
3291As a last resort, you can search for the corrupted objects and attempt
3292to replace them by hand. Back up your repository before attempting this
3293in case you corrupt things even more in the process.
3294
3295We'll assume that the problem is a single missing or corrupted blob,
Shawn Bohrer9e5d87d2007-12-12 22:36:21 -06003296which is sometimes a solvable problem. (Recovering missing trees and
J. Bruce Fields1cdade22007-03-03 22:53:37 -05003297especially commits is *much* harder).
3298
3299Before starting, verify that there is corruption, and figure out where
Dan McGee5162e692007-12-29 00:20:38 -06003300it is with linkgit:git-fsck[1]; this may be time-consuming.
J. Bruce Fields1cdade22007-03-03 22:53:37 -05003301
3302Assume the output looks like this:
3303
3304------------------------------------------------
Junio C Hamanoc6a13b22012-02-28 14:55:39 -08003305$ git fsck --full --no-dangling
J. Bruce Fields1cdade22007-03-03 22:53:37 -05003306broken link from tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8
3307 to blob 4b9458b3786228369c63936db65827de3cc06200
3308missing blob 4b9458b3786228369c63936db65827de3cc06200
3309------------------------------------------------
3310
J. Bruce Fields1cdade22007-03-03 22:53:37 -05003311Now you know that blob 4b9458b3 is missing, and that the tree 2d9263c6
3312points to it. If you could find just one copy of that missing blob
3313object, possibly in some other repository, you could move it into
W. Trevor King1249d8a2013-02-25 17:53:00 -05003314`.git/objects/4b/9458b3...` and be done. Suppose you can't. You can
Dan McGee5162e692007-12-29 00:20:38 -06003315still examine the tree that pointed to it with linkgit:git-ls-tree[1],
J. Bruce Fields1cdade22007-03-03 22:53:37 -05003316which might output something like:
3317
3318------------------------------------------------
3319$ git ls-tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8
3320100644 blob 8d14531846b95bfa3564b58ccfb7913a034323b8 .gitignore
3321100644 blob ebf9bf84da0aab5ed944264a5db2a65fe3a3e883 .mailmap
3322100644 blob ca442d313d86dc67e0a2e5d584b465bd382cbf5c COPYING
3323...
3324100644 blob 4b9458b3786228369c63936db65827de3cc06200 myfile
3325...
3326------------------------------------------------
3327
3328So now you know that the missing blob was the data for a file named
W. Trevor King1249d8a2013-02-25 17:53:00 -05003329`myfile`. And chances are you can also identify the directory--let's
3330say it's in `somedirectory`. If you're lucky the missing copy might be
J. Bruce Fields1cdade22007-03-03 22:53:37 -05003331the same as the copy you have checked out in your working tree at
W. Trevor King1249d8a2013-02-25 17:53:00 -05003332`somedirectory/myfile`; you can test whether that's right with
Dan McGee5162e692007-12-29 00:20:38 -06003333linkgit:git-hash-object[1]:
J. Bruce Fields1cdade22007-03-03 22:53:37 -05003334
3335------------------------------------------------
3336$ git hash-object -w somedirectory/myfile
3337------------------------------------------------
3338
3339which will create and store a blob object with the contents of
Felipe Contrerasa6e5ef72009-04-04 12:38:27 +03003340somedirectory/myfile, and output the SHA-1 of that object. if you're
J. Bruce Fields1cdade22007-03-03 22:53:37 -05003341extremely lucky it might be 4b9458b3786228369c63936db65827de3cc06200, in
3342which case you've guessed right, and the corruption is fixed!
3343
3344Otherwise, you need more information. How do you tell which version of
3345the file has been lost?
3346
3347The easiest way to do this is with:
3348
3349------------------------------------------------
3350$ git log --raw --all --full-history -- somedirectory/myfile
3351------------------------------------------------
3352
3353Because you're asking for raw output, you'll now get something like
3354
3355------------------------------------------------
3356commit abc
3357Author:
3358Date:
3359...
Ann T Ropeaf61d89e2017-12-03 22:27:38 +01003360:100644 100644 4b9458b newsha M somedirectory/myfile
J. Bruce Fields1cdade22007-03-03 22:53:37 -05003361
3362
3363commit xyz
3364Author:
3365Date:
3366
3367...
Ann T Ropeaf61d89e2017-12-03 22:27:38 +01003368:100644 100644 oldsha 4b9458b M somedirectory/myfile
J. Bruce Fields1cdade22007-03-03 22:53:37 -05003369------------------------------------------------
3370
Štěpán Němecedfbbf72012-07-15 00:20:36 +02003371This tells you that the immediately following version of the file was
3372"newsha", and that the immediately preceding version was "oldsha".
J. Bruce Fields1cdade22007-03-03 22:53:37 -05003373You also know the commit messages that went with the change from oldsha
3374to 4b9458b and with the change from 4b9458b to newsha.
3375
3376If you've been committing small enough changes, you may now have a good
3377shot at reconstructing the contents of the in-between state 4b9458b.
3378
3379If you can do that, you can now recreate the missing object with
3380
3381------------------------------------------------
3382$ git hash-object -w <recreated-file>
3383------------------------------------------------
3384
3385and your repository is good again!
3386
W. Trevor King1249d8a2013-02-25 17:53:00 -05003387(Btw, you could have ignored the `fsck`, and started with doing a
J. Bruce Fields1cdade22007-03-03 22:53:37 -05003388
3389------------------------------------------------
3390$ git log --raw --all
3391------------------------------------------------
3392
Ann T Ropeaf61d89e2017-12-03 22:27:38 +01003393and just looked for the sha of the missing object (4b9458b) in that
W. Trevor Kingda2c7b32013-02-10 10:10:39 -05003394whole thing. It's up to you--Git does *have* a lot of information, it is
J. Bruce Fields1cdade22007-03-03 22:53:37 -05003395just missing one particular blob version.
3396
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04003397[[the-index]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02003398=== The index
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003399
W. Trevor King1249d8a2013-02-25 17:53:00 -05003400The index is a binary file (generally kept in `.git/index`) containing a
Felipe Contrerasa6e5ef72009-04-04 12:38:27 +03003401sorted list of path names, each with permissions and the SHA-1 of a blob
Dan McGee5162e692007-12-29 00:20:38 -06003402object; linkgit:git-ls-files[1] can show you the contents of the index:
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003403
J. Bruce Fields1c097892007-09-03 12:59:55 -04003404-------------------------------------------------
3405$ git ls-files --stage
3406100644 63c918c667fa005ff12ad89437f2fdc80926e21c 0 .gitignore
3407100644 5529b198e8d14decbe4ad99db3f7fb632de0439d 0 .mailmap
3408100644 6ff87c4664981e4397625791c8ea3bbb5f2279a3 0 COPYING
3409100644 a37b2152bd26be2c2289e1f57a292534a51a93c7 0 Documentation/.gitignore
3410100644 fbefe9a45b00a54b58d94d06eca48b03d40a50e0 0 Documentation/Makefile
3411...
3412100644 2511aef8d89ab52be5ec6a5e46236b4b6bcd07ea 0 xdiff/xtypes.h
3413100644 2ade97b2574a9f77e7ae4002a4e07a6a38e46d07 0 xdiff/xutils.c
3414100644 d5de8292e05e7c36c4b68857c1cf9855e3d2f70a 0 xdiff/xutils.h
3415-------------------------------------------------
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003416
J. Bruce Fields1c097892007-09-03 12:59:55 -04003417Note that in older documentation you may see the index called the
3418"current directory cache" or just the "cache". It has three important
3419properties:
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003420
J. Bruce Fields1c097892007-09-03 12:59:55 -040034211. The index contains all the information necessary to generate a single
3422(uniquely determined) tree object.
3423+
Dan McGee5162e692007-12-29 00:20:38 -06003424For example, running linkgit:git-commit[1] generates this tree object
J. Bruce Fields1c097892007-09-03 12:59:55 -04003425from the index, stores it in the object database, and uses it as the
3426tree object associated with the new commit.
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003427
J. Bruce Fields1c097892007-09-03 12:59:55 -040034282. The index enables fast comparisons between the tree object it defines
3429and the working tree.
3430+
3431It does this by storing some additional data for each entry (such as
3432the last modified time). This data is not displayed above, and is not
3433stored in the created tree object, but it can be used to determine
3434quickly which files in the working directory differ from what was
Thomas Ackermann2de9b712013-01-21 20:17:53 +01003435stored in the index, and thus save Git from having to read all of the
J. Bruce Fields1c097892007-09-03 12:59:55 -04003436data from such files to look for changes.
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003437
J. Bruce Fields1c097892007-09-03 12:59:55 -040034383. It can efficiently represent information about merge conflicts
3439between different tree objects, allowing each pathname to be
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003440associated with sufficient information about the trees involved that
J. Bruce Fields1c097892007-09-03 12:59:55 -04003441you can create a three-way merge between them.
3442+
3443We saw in <<conflict-resolution>> that during a merge the index can
3444store multiple versions of a single file (called "stages"). The third
Dan McGee5162e692007-12-29 00:20:38 -06003445column in the linkgit:git-ls-files[1] output above is the stage
J. Bruce Fields1c097892007-09-03 12:59:55 -04003446number, and will take on values other than 0 for files with merge
3447conflicts.
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003448
J. Bruce Fields1c097892007-09-03 12:59:55 -04003449The index is thus a sort of temporary staging area, which is filled with
3450a tree which you are in the process of working on.
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003451
J. Bruce Fields1c097892007-09-03 12:59:55 -04003452If you blow the index away entirely, you generally haven't lost any
3453information as long as you have the name of the tree that it described.
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003454
Miklos Vajna38a457b2007-09-20 02:34:14 +02003455[[submodules]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02003456== Submodules
Miklos Vajna38a457b2007-09-20 02:34:14 +02003457
Michael Smith6dd14362007-09-25 08:44:38 -04003458Large projects are often composed of smaller, self-contained modules. For
3459example, an embedded Linux distribution's source tree would include every
3460piece of software in the distribution with some local modifications; a movie
3461player might need to build against a specific, known-working version of a
3462decompression library; several independent programs might all share the same
3463build scripts.
Miklos Vajna38a457b2007-09-20 02:34:14 +02003464
Michael Smith6dd14362007-09-25 08:44:38 -04003465With centralized revision control systems this is often accomplished by
3466including every module in one single repository. Developers can check out
3467all modules or only the modules they need to work with. They can even modify
3468files across several modules in a single commit while moving things around
3469or updating APIs and translations.
3470
3471Git does not allow partial checkouts, so duplicating this approach in Git
3472would force developers to keep a local copy of modules they are not
3473interested in touching. Commits in an enormous checkout would be slower
3474than you'd expect as Git would have to scan every directory for changes.
3475If modules have a lot of local history, clones would take forever.
3476
3477On the plus side, distributed revision control systems can much better
3478integrate with external sources. In a centralized model, a single arbitrary
3479snapshot of the external project is exported from its own revision control
3480and then imported into the local revision control on a vendor branch. All
3481the history is hidden. With distributed revision control you can clone the
3482entire external history and much more easily follow development and re-merge
3483local changes.
3484
3485Git's submodule support allows a repository to contain, as a subdirectory, a
3486checkout of an external project. Submodules maintain their own identity;
3487the submodule support just stores the submodule repository location and
3488commit ID, so other developers who clone the containing project
3489("superproject") can easily clone all the submodules at the same revision.
3490Partial checkouts of the superproject are possible: you can tell Git to
3491clone none, some or all of the submodules.
3492
Dan McGee5162e692007-12-29 00:20:38 -06003493The linkgit:git-submodule[1] command is available since Git 1.5.3. Users
Michael Smith6dd14362007-09-25 08:44:38 -04003494with Git 1.5.2 can look up the submodule commits in the repository and
3495manually check them out; earlier versions won't recognize the submodules at
3496all.
Miklos Vajna38a457b2007-09-20 02:34:14 +02003497
Thomas Ackermannddd4dde2013-08-27 19:59:21 +02003498To see how submodule support works, create four example
Miklos Vajna38a457b2007-09-20 02:34:14 +02003499repositories that can be used later as a submodule:
3500
3501-------------------------------------------------
3502$ mkdir ~/git
3503$ cd ~/git
3504$ for i in a b c d
3505do
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 ..
3513done
3514-------------------------------------------------
3515
3516Now 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
3523do
Abhijit Menon-Sena56bf582008-07-30 01:23:16 +05303524 git submodule add ~/git/$i $i
Miklos Vajna38a457b2007-09-20 02:34:14 +02003525done
3526-------------------------------------------------
3527
3528NOTE: Do not use local URLs here if you plan to publish your superproject!
3529
Felipe Contreras6127c082009-04-04 12:38:23 +03003530See what files `git submodule` created:
Miklos Vajna38a457b2007-09-20 02:34:14 +02003531
3532-------------------------------------------------
3533$ ls -a
3534. .. .git .gitmodules a b c d
3535-------------------------------------------------
3536
Felipe Contreras6127c082009-04-04 12:38:23 +03003537The `git submodule add <repo> <path>` command does a couple of things:
Miklos Vajna38a457b2007-09-20 02:34:14 +02003538
W. Trevor King1249d8a2013-02-25 17:53:00 -05003539- It clones the submodule from `<repo>` to the given `<path>` under the
Abhijit Menon-Sena56bf582008-07-30 01:23:16 +05303540 current directory and by default checks out the master branch.
Dan McGee5162e692007-12-29 00:20:38 -06003541- It adds the submodule's clone path to the linkgit:gitmodules[5] file and
Michael Smith6dd14362007-09-25 08:44:38 -04003542 adds this file to the index, ready to be committed.
Miklos Vajna38a457b2007-09-20 02:34:14 +02003543- It adds the submodule's current commit ID to the index, ready to be
3544 committed.
3545
3546Commit the superproject:
3547
3548-------------------------------------------------
3549$ git commit -m "Add submodules a, b, c and d."
3550-------------------------------------------------
3551
3552Now clone the superproject:
3553
3554-------------------------------------------------
3555$ cd ..
3556$ git clone super cloned
3557$ cd cloned
3558-------------------------------------------------
3559
3560The 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
3572NOTE: The commit object names shown above would be different for you, but they
3573should match the HEAD commit object names of your repositories. You can check
3574it by running `git ls-remote ../a`.
3575
3576Pulling down the submodules is a two-step process. First run `git submodule
3577init` to add the submodule repository URLs to `.git/config`:
3578
3579-------------------------------------------------
3580$ git submodule init
3581-------------------------------------------------
3582
Felipe Contreras6127c082009-04-04 12:38:23 +03003583Now use `git submodule update` to clone the repositories and check out the
Miklos Vajna38a457b2007-09-20 02:34:14 +02003584commits specified in the superproject:
3585
3586-------------------------------------------------
3587$ git submodule update
3588$ cd a
3589$ ls -a
3590. .. .git a.txt
3591-------------------------------------------------
3592
Felipe Contreras6127c082009-04-04 12:38:23 +03003593One major difference between `git submodule update` and `git submodule add` is
3594that `git submodule update` checks out a specific commit, rather than the tip
Miklos Vajna38a457b2007-09-20 02:34:14 +02003595of a branch. It's like checking out a tag: the head is detached, so you're not
3596working on a branch.
3597
3598-------------------------------------------------
3599$ git branch
Thomas Ackermann95f9be52013-08-27 19:56:04 +02003600* (detached from d266b98)
Miklos Vajna38a457b2007-09-20 02:34:14 +02003601 master
3602-------------------------------------------------
3603
3604If you want to make a change within a submodule and you have a detached head,
3605then you should create or checkout a branch, make your changes, publish the
3606change within the submodule, and then update the superproject to reference the
3607new commit:
3608
3609-------------------------------------------------
Nguyễn Thái Ngọc Duy328c6cb2019-03-29 17:39:19 +07003610$ git switch master
Miklos Vajna38a457b2007-09-20 02:34:14 +02003611-------------------------------------------------
3612
3613or
3614
3615-------------------------------------------------
Nguyễn Thái Ngọc Duy328c6cb2019-03-29 17:39:19 +07003616$ git switch -c fix-up
Miklos Vajna38a457b2007-09-20 02:34:14 +02003617-------------------------------------------------
3618
3619then
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
3627diff --git a/a b/a
3628index 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
3639You have to run `git submodule update` after `git pull` if you want to update
3640submodules, too.
3641
Martin Ågrene79b3452019-09-22 13:57:56 +02003642[[pitfalls-with-submodules]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02003643=== Pitfalls with submodules
Miklos Vajna38a457b2007-09-20 02:34:14 +02003644
3645Always publish the submodule change before publishing the change to the
3646superproject that references it. If you forget to publish the submodule change,
3647others 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
3660error: pathspec '261dfac35cb99d380eb966e102c1197139f7fa24' did not match any file(s) known to git.
3661Did you forget to 'git add'?
3662Unable to checkout '261dfac35cb99d380eb966e102c1197139f7fa24' in submodule path 'a'
3663-------------------------------------------------
3664
Thomas Ackermann2de9b712013-01-21 20:17:53 +01003665In older Git versions it could be easily forgotten to commit new or modified
Jens Lehmann8d9e7d52010-02-01 19:09:39 +01003666files in a submodule, which silently leads to similar problems as not pushing
W. Trevor King1249d8a2013-02-25 17:53:00 -05003667the submodule changes. Starting with Git 1.7.0 both `git status` and `git diff`
Jens Lehmann8d9e7d52010-02-01 19:09:39 +01003668in the superproject show submodules as modified when they contain new or
W. Trevor King1249d8a2013-02-25 17:53:00 -05003669modified files to protect against accidentally committing such a state. `git
3670diff` will also add a `-dirty` to the work tree side when generating patch
3671output or used with the `--submodule` option:
Jens Lehmann8d9e7d52010-02-01 19:09:39 +01003672
3673-------------------------------------------------
3674$ git diff
3675diff --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
3682Submodule sub 3f35670..3f35670-dirty:
3683-------------------------------------------------
3684
Miklos Vajna38a457b2007-09-20 02:34:14 +02003685You also should not rewind branches in a submodule beyond commits that were
3686ever recorded in any superproject.
3687
3688It's not safe to run `git submodule update` if you've made and committed
3689changes within a submodule without checking out a branch first. They will be
3690silently overwritten:
3691
3692-------------------------------------------------
3693$ cat a.txt
3694module a
3695$ echo line added from private2 >> a.txt
3696$ git commit -a -m "line added inside private2"
3697$ cd ..
3698$ git submodule update
3699Submodule path 'a': checked out 'd266b9873ad50488163457f025db7cdd9683d88b'
3700$ cd a
3701$ cat a.txt
3702module a
3703-------------------------------------------------
3704
3705NOTE: The changes are still visible in the submodule's reflog.
3706
W. Trevor King91486732013-02-19 05:05:02 -05003707If you have uncommitted changes in your submodule working tree, `git
3708submodule update` will not overwrite them. Instead, you get the usual
3709warning about not being able switch from a dirty branch.
Miklos Vajna38a457b2007-09-20 02:34:14 +02003710
J. Bruce Fields1c6045f2007-09-03 11:27:56 -04003711[[low-level-operations]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02003712== Low-level Git operations
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003713
J. Bruce Fields1c6045f2007-09-03 11:27:56 -04003714Many of the higher-level commands were originally implemented as shell
Thomas Ackermann2de9b712013-01-21 20:17:53 +01003715scripts using a smaller core of low-level Git commands. These can still
3716be useful when doing unusual things with Git, or just as a way to
J. Bruce Fields1c6045f2007-09-03 11:27:56 -04003717understand its inner workings.
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003718
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04003719[[object-manipulation]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02003720=== Object access and manipulation
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04003721
Dan McGee5162e692007-12-29 00:20:38 -06003722The linkgit:git-cat-file[1] command can show the contents of any object,
3723though the higher-level linkgit:git-show[1] is usually more useful.
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04003724
Dan McGee5162e692007-12-29 00:20:38 -06003725The linkgit:git-commit-tree[1] command allows constructing commits with
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04003726arbitrary parents and trees.
3727
Dan McGee5162e692007-12-29 00:20:38 -06003728A tree can be created with linkgit:git-write-tree[1] and its data can be
3729accessed by linkgit:git-ls-tree[1]. Two trees can be compared with
3730linkgit:git-diff-tree[1].
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04003731
Dan McGee5162e692007-12-29 00:20:38 -06003732A tag is created with linkgit:git-mktag[1], and the signature can be
3733verified by linkgit:git-verify-tag[1], though it is normally simpler to
3734use linkgit:git-tag[1] for both.
J. Bruce Fields1bbf1c72007-06-10 15:15:08 -04003735
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04003736[[the-workflow]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02003737=== The Workflow
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003738
Nguyễn Thái Ngọc Duy80f537f2019-04-25 16:45:58 +07003739High-level operations such as linkgit:git-commit[1] and
3740linkgit:git-restore[1] work by moving data
Ralf Wildenhues06ada152007-10-09 23:00:03 +02003741between the working tree, the index, and the object database. Git
3742provides low-level operations which perform each of these steps
3743individually.
J. Bruce Fields1c6045f2007-09-03 11:27:56 -04003744
Thomas Ackermann2de9b712013-01-21 20:17:53 +01003745Generally, all Git operations work on the index file. Some operations
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003746work *purely* on the index file (showing the current state of the
J. Bruce Fields1c6045f2007-09-03 11:27:56 -04003747index), but most operations move data between the index file and either
3748the database or the working directory. Thus there are four main
3749combinations:
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003750
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04003751[[working-directory-to-index]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02003752==== working directory -> index
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003753
Dan McGee5162e692007-12-29 00:20:38 -06003754The linkgit:git-update-index[1] command updates the index with
J. Bruce Fields1c6045f2007-09-03 11:27:56 -04003755information from the working directory. You generally update the
3756index information by just specifying the filename you want to update,
3757like so:
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003758
3759-------------------------------------------------
J. Bruce Fields1c6045f2007-09-03 11:27:56 -04003760$ git update-index filename
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003761-------------------------------------------------
3762
Øystein Walle5fe8f492014-02-05 23:19:43 +01003763but to avoid common mistakes with filename globbing etc., the command
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003764will not normally add totally new entries or remove old entries,
3765i.e. it will normally just update existing cache entries.
3766
Thomas Ackermann2de9b712013-01-21 20:17:53 +01003767To tell Git that yes, you really do realize that certain files no
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003768longer exist, or that new files should be added, you
3769should use the `--remove` and `--add` flags respectively.
3770
3771NOTE! A `--remove` flag does 'not' mean that subsequent filenames will
3772necessarily be removed: if the files still exist in your directory
3773structure, the index will be updated with their new status, not
Johannes Schindelin10455d22007-11-30 11:35:23 +00003774removed. The only thing `--remove` means is that update-index will be
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003775considering a removed file to be a valid thing, and if the file really
3776does not exist any more, it will update the index accordingly.
3777
Jonathan Nieder467c0192008-07-03 00:28:15 -05003778As a special case, you can also do `git update-index --refresh`, which
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003779will refresh the "stat" information of each index to match the current
3780stat information. It will 'not' update the object status itself, and
3781it will only update the fields that are used to quickly test whether
3782an object still matches its old backing store object.
3783
Dan McGee5162e692007-12-29 00:20:38 -06003784The previously introduced linkgit:git-add[1] is just a wrapper for
3785linkgit:git-update-index[1].
J. Bruce Fields1c6045f2007-09-03 11:27:56 -04003786
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04003787[[index-to-object-database]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02003788==== index -> object database
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003789
3790You write your current index file to a "tree" object with the program
3791
3792-------------------------------------------------
J. Bruce Fields1c6045f2007-09-03 11:27:56 -04003793$ git write-tree
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003794-------------------------------------------------
3795
Ralf Wildenhues2ef8ac12007-10-09 23:05:30 +02003796that doesn't come with any options--it will just write out the
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003797current index into the set of tree objects that describe that state,
3798and it will return the name of the resulting top-level tree. You can
3799use that tree to re-generate the index at any time by going in the
3800other direction:
3801
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04003802[[object-database-to-index]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02003803==== object database -> index
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003804
3805You read a "tree" file from the object database, and use that to
Ralf Wildenhues2ef8ac12007-10-09 23:05:30 +02003806populate (and overwrite--don't do this if your index contains any
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003807unsaved state that you might want to restore later!) your current
3808index. Normal operation is just
3809
3810-------------------------------------------------
Felipe Contrerasa6e5ef72009-04-04 12:38:27 +03003811$ git read-tree <SHA-1 of tree>
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003812-------------------------------------------------
3813
3814and your index file will now be equivalent to the tree that you saved
3815earlier. However, that is only your 'index' file: your working
3816directory contents have not been modified.
3817
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04003818[[index-to-working-directory]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02003819==== index -> working directory
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003820
3821You update your working directory from the index by "checking out"
3822files. This is not a very common operation, since normally you'd just
3823keep your files updated, and rather than write to your working
3824directory, you'd tell the index files about the changes in your
Felipe Contreras6127c082009-04-04 12:38:23 +03003825working directory (i.e. `git update-index`).
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003826
3827However, if you decide to jump to a new version, or check out somebody
3828else's version, or just restore a previous tree, you'd populate your
3829index file with read-tree, and then you need to check out the result
3830with
3831
3832-------------------------------------------------
Jonathan Niederb1889c32008-06-30 01:09:04 -05003833$ git checkout-index filename
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003834-------------------------------------------------
3835
3836or, if you want to check out all of the index, use `-a`.
3837
Felipe Contreras6127c082009-04-04 12:38:23 +03003838NOTE! `git checkout-index` normally refuses to overwrite old files, so
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003839if you have an old version of the tree already checked out, you will
W. Trevor King1249d8a2013-02-25 17:53:00 -05003840need to use the `-f` flag ('before' the `-a` flag or the filename) to
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003841'force' the checkout.
3842
3843
3844Finally, there are a few odds and ends which are not purely moving
3845from one representation to the other:
3846
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04003847[[tying-it-all-together]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02003848==== Tying it all together
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003849
W. Trevor King1249d8a2013-02-25 17:53:00 -05003850To commit a tree you have instantiated with `git write-tree`, you'd
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003851create a "commit" object that refers to that tree and the history
Ralf Wildenhues2ef8ac12007-10-09 23:05:30 +02003852behind it--most notably the "parent" commits that preceded it in
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003853history.
3854
3855Normally a "commit" has one parent: the previous state of the tree
3856before a certain change was made. However, sometimes it can have two
3857or more parent commits, in which case we call it a "merge", due to the
3858fact that such a commit brings together ("merges") two or more
3859previous states represented by other commits.
3860
3861In other words, while a "tree" represents a particular directory state
Thomas Ackermannddd4dde2013-08-27 19:59:21 +02003862of a working directory, a "commit" represents that state in time,
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003863and explains how we got there.
3864
3865You create a commit object by giving it the tree that describes the
3866state at the time of the commit, and a list of parents:
3867
3868-------------------------------------------------
Štěpán Němec0adda932010-10-08 19:31:17 +02003869$ git commit-tree <tree> -p <parent> [(-p <parent2>)...]
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003870-------------------------------------------------
3871
3872and then giving the reason for the commit on stdin (either through
3873redirection from a pipe or file, or by just typing it at the tty).
3874
Felipe Contreras6127c082009-04-04 12:38:23 +03003875`git commit-tree` will return the name of the object that represents
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003876that commit, and you should save it away for later use. Normally,
Thomas Ackermann2de9b712013-01-21 20:17:53 +01003877you'd commit a new `HEAD` state, and while Git doesn't care where you
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003878save the note about that state, in practice we tend to just write the
3879result to the file pointed at by `.git/HEAD`, so that we can always see
3880what the last committed state was.
3881
Thomas Ackermann381183f2013-08-27 20:04:58 +02003882Here is a picture that illustrates how various pieces fit together:
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003883
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 Fieldse34caac2007-04-18 00:46:19 -04003921[[examining-the-data]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02003922=== Examining the data
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003923
3924You can examine the data represented in the object database and the
3925index with various helper tools. For every object, you can use
Dan McGee5162e692007-12-29 00:20:38 -06003926linkgit:git-cat-file[1] to examine details about the
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003927object:
3928
3929-------------------------------------------------
Jonathan Niederb1889c32008-06-30 01:09:04 -05003930$ git cat-file -t <objectname>
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003931-------------------------------------------------
3932
3933shows the type of the object, and once you have the type (which is
3934usually implicit in where you find the object), you can use
3935
3936-------------------------------------------------
Jonathan Niederb1889c32008-06-30 01:09:04 -05003937$ git cat-file blob|tree|commit|tag <objectname>
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003938-------------------------------------------------
3939
3940to show its contents. NOTE! Trees have binary content, and as a result
3941there is a special helper for showing that content, called
Felipe Contreras6127c082009-04-04 12:38:23 +03003942`git ls-tree`, which turns the binary content into a more easily
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003943readable form.
3944
3945It's especially instructive to look at "commit" objects, since those
3946tend to be small and fairly self-explanatory. In particular, if you
3947follow the convention of having the top commit name in `.git/HEAD`,
3948you can do
3949
3950-------------------------------------------------
Jonathan Niederb1889c32008-06-30 01:09:04 -05003951$ git cat-file commit HEAD
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003952-------------------------------------------------
3953
3954to see what the top commit was.
3955
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04003956[[merging-multiple-trees]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02003957=== Merging multiple trees
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05003958
Thomas Ackermanne8e99642013-08-27 20:03:09 +02003959Git can help you perform a three-way merge, which can in turn be
3960used for a many-way merge by repeating the merge procedure several
3961times. The usual situation is that you only do one three-way merge
3962(reconciling two lines of history) and commit the result, but if
3963you like to, you can merge several branches in one go.
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003964
Thomas Ackermanne8e99642013-08-27 20:03:09 +02003965To perform a three-way merge, you start with the two commits you
3966want to merge, find their closest common parent (a third commit),
3967and compare the trees corresponding to these three commits.
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003968
Thomas Ackermanne8e99642013-08-27 20:03:09 +02003969To get the "base" for the merge, look up the common parent of two
3970commits:
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003971
3972-------------------------------------------------
Jonathan Niederb1889c32008-06-30 01:09:04 -05003973$ git merge-base <commit1> <commit2>
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003974-------------------------------------------------
3975
Thomas Ackermanne8e99642013-08-27 20:03:09 +02003976This prints the name of a commit they are both based on. You should
3977now look up the tree objects of those commits, which you can easily
3978do with
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003979
3980-------------------------------------------------
Jonathan Niederb1889c32008-06-30 01:09:04 -05003981$ git cat-file commit <commitname> | head -1
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003982-------------------------------------------------
3983
3984since the tree object information is always the first line in a commit
3985object.
3986
J. Bruce Fields1191ee12007-01-29 01:33:55 -05003987Once you know the three trees you are going to merge (the one "original"
J. Bruce Fieldsc64415e2007-05-07 00:56:45 -04003988tree, aka the common tree, and the two "result" trees, aka the branches
J. Bruce Fields1191ee12007-01-29 01:33:55 -05003989you want to merge), you do a "merge" read into the index. This will
3990complain if it has to throw away your old index contents, so you should
Ralf Wildenhues2ef8ac12007-10-09 23:05:30 +02003991make sure that you've committed those--in fact you would normally
J. Bruce Fields1191ee12007-01-29 01:33:55 -05003992always do a merge against your last commit (which should thus match what
3993you have in your current index anyway).
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003994
3995To do the merge, do
3996
3997-------------------------------------------------
Jonathan Niederb1889c32008-06-30 01:09:04 -05003998$ git read-tree -m -u <origtree> <yourtree> <targettree>
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05003999-------------------------------------------------
4000
4001which will do all trivial merge operations for you directly in the
4002index file, and you can just write the result out with
Jonathan Nieder467c0192008-07-03 00:28:15 -05004003`git write-tree`.
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05004004
4005
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04004006[[merging-multiple-trees-2]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02004007=== Merging multiple trees, continued
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05004008
4009Sadly, many merges aren't trivial. If there are files that have
Ralf Wildenhues06ada152007-10-09 23:00:03 +02004010been added, moved or removed, or if both branches have modified the
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05004011same file, you will be left with an index tree that contains "merge
4012entries" in it. Such an index tree can 'NOT' be written out to a tree
4013object, and you will have to resolve any such merge clashes using
4014other tools before you can write out the result.
4015
Jonathan Niederb1889c32008-06-30 01:09:04 -05004016You can examine such index state with `git ls-files --unmerged`
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05004017command. An example:
4018
4019------------------------------------------------
Jonathan Niederb1889c32008-06-30 01:09:04 -05004020$ git read-tree -m $orig HEAD $target
4021$ git ls-files --unmerged
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05004022100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello.c
4023100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello.c
4024100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello.c
4025------------------------------------------------
4026
Jonathan Niederb1889c32008-06-30 01:09:04 -05004027Each line of the `git ls-files --unmerged` output begins with
Felipe Contrerasa6e5ef72009-04-04 12:38:27 +03004028the blob mode bits, blob SHA-1, 'stage number', and the
Thomas Ackermann2de9b712013-01-21 20:17:53 +01004029filename. The 'stage number' is Git's way to say which tree it
Štěpán Němecedfbbf72012-07-15 00:20:36 +02004030came from: stage 1 corresponds to the `$orig` tree, stage 2 to
4031the `HEAD` tree, and stage 3 to the `$target` tree.
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05004032
4033Earlier we said that trivial merges are done inside
Felipe Contreras6127c082009-04-04 12:38:23 +03004034`git read-tree -m`. For example, if the file did not change
Justin Lebara58088a2014-03-31 15:11:44 -07004035from `$orig` to `HEAD` or `$target`, or if the file changed
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05004036from `$orig` to `HEAD` and `$orig` to `$target` the same way,
4037obviously the final outcome is what is in `HEAD`. What the
4038above example shows is that file `hello.c` was changed from
4039`$orig` to `HEAD` and `$orig` to `$target` in a different way.
4040You could resolve this by running your favorite 3-way merge
Thomas Ackermann2de9b712013-01-21 20:17:53 +01004041program, e.g. `diff3`, `merge`, or Git's own merge-file, on
J. Bruce Fieldsc64415e2007-05-07 00:56:45 -04004042the blob objects from these three stages yourself, like this:
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05004043
4044------------------------------------------------
Ann T Ropeaf61d89e2017-12-03 22:27:38 +01004045$ 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 Fieldsc64415e2007-05-07 00:56:45 -04004048$ git merge-file hello.c~2 hello.c~1 hello.c~3
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05004049------------------------------------------------
4050
4051This would leave the merge result in `hello.c~2` file, along
4052with conflict markers if there are conflicts. After verifying
Thomas Ackermann2de9b712013-01-21 20:17:53 +01004053the merge result makes sense, you can tell Git what the final
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05004054merge result for this file is by:
4055
4056-------------------------------------------------
4057$ mv -f hello.c~2 hello.c
Jonathan Niederb1889c32008-06-30 01:09:04 -05004058$ git update-index hello.c
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05004059-------------------------------------------------
4060
Felipe Contreras6127c082009-04-04 12:38:23 +03004061When a path is in the "unmerged" state, running `git update-index` for
Thomas Ackermann2de9b712013-01-21 20:17:53 +01004062that path tells Git to mark the path resolved.
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05004063
Thomas Ackermann2de9b712013-01-21 20:17:53 +01004064The above is the description of a Git merge at the lowest level,
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05004065to help you understand what conceptually happens under the hood.
Thomas Ackermann2de9b712013-01-21 20:17:53 +01004066In practice, nobody, not even Git itself, runs `git cat-file` three times
Felipe Contreras6127c082009-04-04 12:38:23 +03004067for this. There is a `git merge-index` program that extracts the
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05004068stages to temporary files and calls a "merge" script on it:
4069
4070-------------------------------------------------
Jonathan Niederb1889c32008-06-30 01:09:04 -05004071$ git merge-index git-merge-one-file hello.c
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05004072-------------------------------------------------
4073
Felipe Contreras6127c082009-04-04 12:38:23 +03004074and that is what higher level `git merge -s resolve` is implemented with.
J. Bruce Fieldsb181d572007-01-27 01:03:07 -05004075
J. Bruce Fields971aa712007-08-30 22:49:33 -04004076[[hacking-git]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02004077== Hacking Git
J. Bruce Fields971aa712007-08-30 22:49:33 -04004078
Thomas Ackermann2de9b712013-01-21 20:17:53 +01004079This chapter covers internal details of the Git implementation which
4080probably only Git developers need to understand.
J. Bruce Fields971aa712007-08-30 22:49:33 -04004081
J. Bruce Fieldsf2327c62007-08-30 23:07:05 -04004082[[object-details]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02004083=== Object storage format
J. Bruce Fieldsf2327c62007-08-30 23:07:05 -04004084
4085All objects have a statically determined "type" which identifies the
4086format of the object (i.e. how it is used, and how it can refer to other
4087objects). There are currently four different object types: "blob",
4088"tree", "commit", and "tag".
4089
4090Regardless of object type, all objects share the following
4091characteristics: they are all deflated with zlib, and have a header
4092that not only specifies their type, but also provides size information
Felipe Contrerasa6e5ef72009-04-04 12:38:27 +03004093about the data in the object. It's worth noting that the SHA-1 hash
J. Bruce Fieldsf2327c62007-08-30 23:07:05 -04004094that is used to name the object is the hash of the original data
4095plus this header, so `sha1sum` 'file' does not match the object name
Dirk Gouders28636d72024-03-12 11:41:56 +01004096for 'file' (the earliest versions of Git hashed slightly differently
4097but the conclusion is still the same).
4098
4099The following is a short example that demonstrates how these hashes
4100can be generated manually:
4101
4102Let's assume a small text file with some simple content:
4103
4104-------------------------------------------------
4105$ echo "Hello world" >hello.txt
4106-------------------------------------------------
4107
4108We 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
4118802992c4220de19a90767f3000a79a31b98d0df7 -
4119-------------------------------------------------
4120
4121This manually constructed hash can be verified using `git hash-object`
4122which of course hides the addition of the header:
4123
4124-------------------------------------------------
4125$ git hash-object hello.txt
4126802992c4220de19a90767f3000a79a31b98d0df7
4127-------------------------------------------------
J. Bruce Fieldsf2327c62007-08-30 23:07:05 -04004128
4129As a result, the general consistency of an object can always be tested
4130independently of the contents or the type of the object: all objects can
4131be validated by verifying that (a) their hashes match the content of the
4132file and (b) the object successfully inflates to a stream of bytes that
W. Trevor King1249d8a2013-02-25 17:53:00 -05004133forms a sequence of
Jean-Noël Avila2162f9f2023-12-25 21:21:26 +00004134`<ascii-type-without-space> + <space> + <ascii-decimal-size> +
4135<byte\0> + <binary-object-data>`.
J. Bruce Fieldsf2327c62007-08-30 23:07:05 -04004136
4137The structured objects can further have their structure and
4138connectivity to other objects verified. This is generally done with
Felipe Contreras6127c082009-04-04 12:38:23 +03004139the `git fsck` program, which generates a full dependency graph
J. Bruce Fieldsf2327c62007-08-30 23:07:05 -04004140of all objects, and verifies their internal consistency (in addition
4141to just verifying their superficial consistency through the hash).
4142
Johannes Schindelin126640a2007-05-10 12:36:15 +02004143[[birdview-on-the-source-code]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02004144=== A birds-eye view of Git's source code
Johannes Schindelin126640a2007-05-10 12:36:15 +02004145
J. Bruce Fieldsa5fc33b2007-05-12 19:48:31 -04004146It is not always easy for new developers to find their way through Git's
4147source code. This section gives you a little guidance to show where to
4148start.
Johannes Schindelin126640a2007-05-10 12:36:15 +02004149
J. Bruce Fieldsa5fc33b2007-05-12 19:48:31 -04004150A good place to start is with the contents of the initial commit, with:
Johannes Schindelin126640a2007-05-10 12:36:15 +02004151
4152----------------------------------------------------
Nguyễn Thái Ngọc Duy328c6cb2019-03-29 17:39:19 +07004153$ git switch --detach e83c5163
Johannes Schindelin126640a2007-05-10 12:36:15 +02004154----------------------------------------------------
4155
Thomas Ackermann2de9b712013-01-21 20:17:53 +01004156The initial revision lays the foundation for almost everything Git has
Dirk Gouders28636d72024-03-12 11:41:56 +01004157today (even though details may differ in a few places), but is small
4158enough to read in one sitting.
Johannes Schindelin126640a2007-05-10 12:36:15 +02004159
J. Bruce Fieldsa5fc33b2007-05-12 19:48:31 -04004160Note that terminology has changed since that revision. For example, the
4161README in that revision uses the word "changeset" to describe what we
4162now call a <<def_commit_object,commit>>.
Johannes Schindelin126640a2007-05-10 12:36:15 +02004163
Elijah Newrenbc5c5ec2023-05-16 06:33:57 +00004164Also, we do not call it "cache" any more, but rather "index"; however,
4165the file is still called `read-cache.h`.
Johannes Schindelin126640a2007-05-10 12:36:15 +02004166
J. Bruce Fieldsa5fc33b2007-05-12 19:48:31 -04004167If you grasp the ideas in that initial commit, you should check out a
Elijah Newrenbc5c5ec2023-05-16 06:33:57 +00004168more recent version and skim `read-cache-ll.h`, `object.h` and `commit.h`.
Johannes Schindelin126640a2007-05-10 12:36:15 +02004169
4170In the early days, Git (in the tradition of UNIX) was a bunch of programs
4171which were extremely simple, and which you used in scripts, piping the
4172output of one into another. This turned out to be good for initial
4173development, since it was easier to test new things. However, recently
4174many 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,
4176and to avoid code duplication.
4177
4178By now, you know what the index is (and find the corresponding data
Elijah Newrenbc5c5ec2023-05-16 06:33:57 +00004179structures in `read-cache-ll.h`), and that there are just a couple of
4180object types (blobs, trees, commits and tags) which inherit their
4181common 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 Schindelin126640a2007-05-10 12:36:15 +02004184
4185Now is a good point to take a break to let this information sink in.
4186
4187Next step: get familiar with the object naming. Read <<naming-commits>>.
4188There are quite a few ways to name an object (and not only revisions!).
4189All of these are handled in `sha1_name.c`. Just have a quick look at
4190the function `get_sha1()`. A lot of the special handling is done by
4191functions like `get_sha1_basic()` or the likes.
4192
4193This is just to get you into the groove for the most libified part of Git:
4194the revision walker.
4195
Felipe Contreras6127c082009-04-04 12:38:23 +03004196Basically, the initial version of `git log` was a shell script:
Johannes Schindelin126640a2007-05-10 12:36:15 +02004197
4198----------------------------------------------------------------
4199$ git-rev-list --pretty $(git-rev-parse --default HEAD "$@") | \
4200 LESS=-S ${PAGER:-less}
4201----------------------------------------------------------------
4202
4203What does this mean?
4204
Felipe Contreras6127c082009-04-04 12:38:23 +03004205`git rev-list` is the original version of the revision walker, which
Johannes Schindelin126640a2007-05-10 12:36:15 +02004206_always_ printed a list of revisions to stdout. It is still functional,
Ori Avtalion57f6ec02009-08-07 17:24:21 +03004207and needs to, since most new Git commands start out as scripts using
Felipe Contreras6127c082009-04-04 12:38:23 +03004208`git rev-list`.
Johannes Schindelin126640a2007-05-10 12:36:15 +02004209
Felipe Contreras6127c082009-04-04 12:38:23 +03004210`git rev-parse` is not as important any more; it was only used to filter out
Johannes Schindelin126640a2007-05-10 12:36:15 +02004211options that were relevant for the different plumbing commands that were
4212called by the script.
4213
Felipe Contreras6127c082009-04-04 12:38:23 +03004214Most of what `git rev-list` did is contained in `revision.c` and
Johannes Schindelin126640a2007-05-10 12:36:15 +02004215`revision.h`. It wraps the options in a struct named `rev_info`, which
4216controls how and what revisions are walked, and more.
4217
Felipe Contreras6127c082009-04-04 12:38:23 +03004218The original job of `git rev-parse` is now taken by the function
Jason St. John06ab60c2014-05-21 14:52:26 -04004219`setup_revisions()`, which parses the revisions and the common command-line
Johannes Schindelin126640a2007-05-10 12:36:15 +02004220options for the revision walker. This information is stored in the struct
Jason St. John06ab60c2014-05-21 14:52:26 -04004221`rev_info` for later consumption. You can do your own command-line option
Johannes Schindelin126640a2007-05-10 12:36:15 +02004222parsing after calling `setup_revisions()`. After that, you have to call
4223`prepare_revision_walk()` for initialization, and then you can get the
4224commits one by one with the function `get_revision()`.
4225
4226If you are interested in more details of the revision walking process,
4227just have a look at the first implementation of `cmd_log()`; call
Jeff King6cf378f2012-04-26 04:51:57 -04004228`git show v1.3.0~155^2~4` and scroll down to that function (note that you
Johannes Schindelin126640a2007-05-10 12:36:15 +02004229no longer need to call `setup_pager()` directly).
4230
Felipe Contreras6127c082009-04-04 12:38:23 +03004231Nowadays, `git log` is a builtin, which means that it is _contained_ in the
Johannes Schindelin126640a2007-05-10 12:36:15 +02004232command `git`. The source side of a builtin is
4233
Phil Hord09b7e222013-06-18 13:44:58 -04004234- 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 Schindelin126640a2007-05-10 12:36:15 +02004237
4238- an entry in the `commands[]` array in `git.c`, and
4239
4240- an entry in `BUILTIN_OBJECTS` in the `Makefile`.
4241
4242Sometimes, more than one builtin is contained in one source file. For
Phil Hord09b7e222013-06-18 13:44:58 -04004243example, `cmd_whatchanged()` and `cmd_log()` both reside in `builtin/log.c`,
Johannes Schindelin126640a2007-05-10 12:36:15 +02004244since 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 Contreras6127c082009-04-04 12:38:23 +03004248`git log` looks more complicated in C than it does in the original script,
Johannes Schindelin126640a2007-05-10 12:36:15 +02004249but that allows for a much greater flexibility and performance.
4250
4251Here again it is a good point to take a pause.
4252
4253Lesson three is: study the code. Really, it is the best way to learn about
4254the organization of Git (after you know the basic concepts).
4255
4256So, think about something which you are interested in, say, "how can I
4257access a blob just knowing the object name of it?". The first step is to
4258find a Git command with which you can do it. In this example, it is either
Felipe Contreras6127c082009-04-04 12:38:23 +03004259`git show` or `git cat-file`.
Johannes Schindelin126640a2007-05-10 12:36:15 +02004260
Felipe Contreras6127c082009-04-04 12:38:23 +03004261For the sake of clarity, let's stay with `git cat-file`, because it
Johannes Schindelin126640a2007-05-10 12:36:15 +02004262
4263- is plumbing, and
4264
4265- was around even in the initial commit (it literally went only through
Phil Hord09b7e222013-06-18 13:44:58 -04004266 some 20 revisions as `cat-file.c`, was renamed to `builtin/cat-file.c`
Johannes Schindelin126640a2007-05-10 12:36:15 +02004267 when made a builtin, and then saw less than 10 versions).
4268
Phil Hord09b7e222013-06-18 13:44:58 -04004269So, look into `builtin/cat-file.c`, search for `cmd_cat_file()` and look what
Johannes Schindelin126640a2007-05-10 12:36:15 +02004270it does.
4271
4272------------------------------------------------------------------
4273 git_config(git_default_config);
4274 if (argc != 3)
Felipe Contreras6127c082009-04-04 12:38:23 +03004275 usage("git cat-file [-t|-s|-e|-p|<type>] <sha1>");
Johannes Schindelin126640a2007-05-10 12:36:15 +02004276 if (get_sha1(argv[2], sha1))
4277 die("Not a valid object name %s", argv[2]);
4278------------------------------------------------------------------
4279
4280Let's skip over the obvious details; the only really interesting part
4281here is the call to `get_sha1()`. It tries to interpret `argv[2]` as an
4282object name, and if it refers to an object which is present in the current
4283repository, it writes the resulting SHA-1 into the variable `sha1`.
4284
4285Two 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 Wildenhues2ef8ac12007-10-09 23:05:30 +02004289 negative numbers in case of different errors--and 0 on success.
Johannes Schindelin126640a2007-05-10 12:36:15 +02004290
4291- the variable `sha1` in the function signature of `get_sha1()` is `unsigned
Jeff King6cf378f2012-04-26 04:51:57 -04004292 char *`, but is actually expected to be a pointer to `unsigned
Johannes Schindelin126640a2007-05-10 12:36:15 +02004293 char[20]`. This variable will contain the 160-bit SHA-1 of the given
Jeff King6cf378f2012-04-26 04:51:57 -04004294 commit. Note that whenever a SHA-1 is passed as `unsigned char *`, it
Johannes Schindelin126640a2007-05-10 12:36:15 +02004295 is the binary representation, as opposed to the ASCII representation in
J. Bruce Fieldsa5fc33b2007-05-12 19:48:31 -04004296 hex characters, which is passed as `char *`.
Johannes Schindelin126640a2007-05-10 12:36:15 +02004297
4298You will see both of these things throughout the code.
4299
4300Now, for the meat:
4301
4302-----------------------------------------------------------------------------
4303 case 0:
4304 buf = read_object_with_reference(sha1, argv[1], &size, NULL);
4305-----------------------------------------------------------------------------
4306
4307This is how you read a blob (actually, not only a blob, but any type of
4308object). To know how the function `read_object_with_reference()` actually
4309works, find the source code for it (something like `git grep
Thomas Ackermann2de9b712013-01-21 20:17:53 +01004310read_object_with | grep ":[a-z]"` in the Git repository), and read
Johannes Schindelin126640a2007-05-10 12:36:15 +02004311the source.
4312
4313To 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
4319Sometimes, you do not know where to look for a feature. In many such cases,
Felipe Contreras6127c082009-04-04 12:38:23 +03004320it helps to search through the output of `git log`, and then `git show` the
Johannes Schindelin126640a2007-05-10 12:36:15 +02004321corresponding commit.
4322
Felipe Contreras6127c082009-04-04 12:38:23 +03004323Example: If you know that there was some test case for `git bundle`, but
Johannes Schindelin126640a2007-05-10 12:36:15 +02004324do not remember where it was (yes, you _could_ `git grep bundle t/`, but that
4325does not illustrate the point!):
4326
4327------------------------
4328$ git log --no-merges t/
4329------------------------
4330
4331In the pager (`less`), just search for "bundle", go a few lines back,
Ann T Ropeaf61d89e2017-12-03 22:27:38 +01004332and see that it is in commit 18449ab0. Now just copy this object name,
Johannes Schindelin126640a2007-05-10 12:36:15 +02004333and paste it into the command line
4334
4335-------------------
4336$ git show 18449ab0
4337-------------------
4338
4339Voila.
4340
4341Another example: Find out what to do in order to make some script a
4342builtin:
4343
4344-------------------------------------------------
Phil Hord09b7e222013-06-18 13:44:58 -04004345$ git log --no-merges --diff-filter=A builtin/*.c
Johannes Schindelin126640a2007-05-10 12:36:15 +02004346-------------------------------------------------
4347
4348You see, Git is actually the best tool to find out about the source of Git
4349itself!
4350
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04004351[[glossary]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02004352== Git Glossary
Christian Couder497c8332008-05-29 19:21:46 +02004353
마누엘03920ac2017-01-02 17:03:57 +01004354[[git-explained]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02004355=== Git explained
마누엘03920ac2017-01-02 17:03:57 +01004356
Christian Couder497c8332008-05-29 19:21:46 +02004357include::glossary-content.txt[]
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05004358
J. Bruce Fields2624d9a2007-05-12 22:55:40 -04004359[[git-quick-start]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02004360[appendix]
4361== Git Quick Reference
J. Bruce Fields2624d9a2007-05-12 22:55:40 -04004362
J. Bruce Fields99f171b2007-06-05 18:33:27 -04004363This is a quick summary of the major commands; the previous chapters
4364explain how these work in more detail.
J. Bruce Fields2624d9a2007-05-12 22:55:40 -04004365
4366[[quick-creating-a-new-repository]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02004367=== Creating a new repository
J. Bruce Fields2624d9a2007-05-12 22:55:40 -04004368
4369From a tarball:
4370
4371-----------------------------------------------
4372$ tar xzf project.tar.gz
4373$ cd project
4374$ git init
4375Initialized empty Git repository in .git/
4376$ git add .
4377$ git commit
4378-----------------------------------------------
4379
4380From a remote repository:
4381
4382-----------------------------------------------
4383$ git clone git://example.com/pub/project.git
4384$ cd project
4385-----------------------------------------------
4386
4387[[managing-branches]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02004388=== Managing branches
J. Bruce Fields2624d9a2007-05-12 22:55:40 -04004389
4390-----------------------------------------------
Nguyễn Thái Ngọc Duy328c6cb2019-03-29 17:39:19 +07004391$ 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 Fields2624d9a2007-05-12 22:55:40 -04004395-----------------------------------------------
4396
Ralf Wildenhues06ada152007-10-09 23:00:03 +02004397Instead of basing a new branch on current HEAD (the default), use:
J. Bruce Fields2624d9a2007-05-12 22:55:40 -04004398
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
4407Create and switch to a new branch at the same time:
4408
4409-----------------------------------------------
Nguyễn Thái Ngọc Duy328c6cb2019-03-29 17:39:19 +07004410$ git switch -c new v2.6.15
J. Bruce Fields2624d9a2007-05-12 22:55:40 -04004411-----------------------------------------------
4412
4413Update 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 Duy328c6cb2019-03-29 17:39:19 +07004421$ git switch -c masterwork origin/master
J. Bruce Fields2624d9a2007-05-12 22:55:40 -04004422-----------------------------------------------
4423
4424Fetch a branch from a different repository, and give it a new
4425name 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
4432Keep 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
4437example
4438origin
4439$ git remote show example # get details
4440* remote example
4441 URL: git://example.com/project.git
4442 Tracked remote branches
Johannes Sixt20244ea2008-10-22 09:39:47 +02004443 master
4444 next
4445 ...
J. Bruce Fields2624d9a2007-05-12 22:55:40 -04004446$ git fetch example # update branches from example
4447$ git branch -r # list all remote branches
4448-----------------------------------------------
4449
4450
4451[[exploring-history]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02004452=== Exploring history
J. Bruce Fields2624d9a2007-05-12 22:55:40 -04004453
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
4473Search 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
4479Bisecting: 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 Ågrenfd5b8202019-09-22 13:57:57 +02004487=== Making changes
J. Bruce Fields2624d9a2007-05-12 22:55:40 -04004488
Thomas Ackermann2de9b712013-01-21 20:17:53 +01004489Make sure Git knows who to blame:
J. Bruce Fields2624d9a2007-05-12 22:55:40 -04004490
4491------------------------------------------------
4492$ cat >>~/.gitconfig <<\EOF
4493[user]
4494 name = Your Name Comes Here
4495 email = you@yourdomain.example.com
4496EOF
4497------------------------------------------------
4498
4499Select file contents to include in the next commit, then make the
4500commit:
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
4509Or, 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 Ågrenfd5b8202019-09-22 13:57:57 +02004517=== Merging
J. Bruce Fields2624d9a2007-05-12 22:55:40 -04004518
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 Ågrenfd5b8202019-09-22 13:57:57 +02004527=== Sharing your changes
J. Bruce Fields2624d9a2007-05-12 22:55:40 -04004528
4529Importing 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 Ackermann2de9b712013-01-21 20:17:53 +01004537Fetch a branch in a different Git repository, then merge into the
J. Bruce Fields2624d9a2007-05-12 22:55:40 -04004538current branch:
4539
4540-----------------------------------------------
4541$ git pull git://example.com/project.git theirbranch
4542-----------------------------------------------
4543
4544Store the fetched branch into a local branch before merging into the
4545current branch:
4546
4547-----------------------------------------------
4548$ git pull git://example.com/project.git theirbranch:mybranch
4549-----------------------------------------------
4550
4551After creating commits on a local branch, update the remote
4552branch with your commits:
4553
4554-----------------------------------------------
4555$ git push ssh://example.com/project.git mybranch:theirbranch
4556-----------------------------------------------
4557
4558When remote and local branch are both named "test":
4559
4560-----------------------------------------------
4561$ git push ssh://example.com/project.git test
4562-----------------------------------------------
4563
4564Shortcut 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 Ågrenfd5b8202019-09-22 13:57:57 +02004572=== Repository maintenance
J. Bruce Fields2624d9a2007-05-12 22:55:40 -04004573
4574Check for corruption:
4575
4576-----------------------------------------------
4577$ git fsck
4578-----------------------------------------------
4579
4580Recompress, remove unused cruft:
4581
4582-----------------------------------------------
4583$ git gc
4584-----------------------------------------------
4585
4586
J. Bruce Fieldse34caac2007-04-18 00:46:19 -04004587[[todo]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02004588[appendix]
4589== Notes and todo list for this manual
J. Bruce Fields6bd9b682007-01-07 22:58:14 -05004590
마누엘03920ac2017-01-02 17:03:57 +01004591[[todo-list]]
Martin Ågrenfd5b8202019-09-22 13:57:57 +02004592=== Todo list
마누엘03920ac2017-01-02 17:03:57 +01004593
J. Bruce Fields6bd9b682007-01-07 22:58:14 -05004594This is a work in progress.
4595
4596The basic requirements:
J. Bruce Fieldsecd95b52007-09-02 23:28:49 -04004597
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 Ackermann2de9b712013-01-21 20:17:53 +01004600 any special knowledge of Git. If necessary, any other prerequisites
J. Bruce Fieldsecd95b52007-09-02 23:28:49 -04004601 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 Contreras6127c082009-04-04 12:38:23 +03004605 than "the `git am` command"
J. Bruce Fields6bd9b682007-01-07 22:58:14 -05004606
J. Bruce Fieldsd5cd5de2007-01-09 00:18:09 -05004607Think about how to create a clear chapter dependency graph that will
4608allow people to get to important topics without necessarily reading
4609everything in between.
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05004610
W. Trevor King1249d8a2013-02-25 17:53:00 -05004611Scan `Documentation/` for other stuff left out; in particular:
J. Bruce Fieldsecd95b52007-09-02 23:28:49 -04004612
4613- howto's
W. Trevor King1249d8a2013-02-25 17:53:00 -05004614- some of `technical/`?
J. Bruce Fieldsecd95b52007-09-02 23:28:49 -04004615- hooks
Dan McGee5162e692007-12-29 00:20:38 -06004616- list of commands in linkgit:git[1]
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05004617
4618Scan email archives for other stuff left out
4619
4620Scan man pages to see if any assume more background than this manual
4621provides.
4622
J. Bruce Fields2f997102007-01-14 22:43:47 -05004623Add more good examples. Entire sections of just cookbook examples
4624might be a good idea; maybe make an "advanced examples" section a
4625standard end-of-chapter section?
J. Bruce Fieldsd19fbc32007-01-07 19:23:49 -05004626
4627Include cross-references to the glossary, where appropriate.
4628
Pavel Roskin3dff5372007-02-03 23:49:16 -05004629Add a section on working with other version control systems, including
J. Bruce Fields9a241222007-01-29 01:43:33 -05004630CVS, Subversion, and just imports of series of release tarballs.
4631
J. Bruce Fields0b375ab2007-01-30 12:48:48 -05004632Write a chapter on using plumbing and writing scripts.
J. Bruce Fieldsd9bd3212007-02-06 02:55:07 -05004633
4634Alternates, clone -reference, etc.
4635
J. Bruce Fields1cdade22007-03-03 22:53:37 -05004636More on recovery from repository corruption. See:
Denton Liudcee0372019-12-02 11:26:18 -08004637 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/