blob: 7567955bad8552800b92ade66007c442dc000715 [file] [log] [blame]
David Greaves2cf565c2005-05-10 22:32:30 +01001git-read-tree(1)
2================
David Greaves2cf565c2005-05-10 22:32:30 +01003
4NAME
5----
Lukas_Sandström5f3aa192005-11-11 02:12:27 +01006git-read-tree - Reads tree information into the index
David Greaves2cf565c2005-05-10 22:32:30 +01007
8
9SYNOPSIS
10--------
Martin von Zweigbergk7791a1d2011-07-01 22:38:26 -040011[verse]
Ævar Arnfjörð Bjarmasone8eeda12022-10-13 17:39:15 +020012'git read-tree' [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)
Elijah Newren491a7572021-09-27 16:33:40 +000013 [-u | -i]] [--index-output=<file>] [--no-sparse-checkout]
Jan Krügerfb1bb962010-09-10 15:28:59 +020014 (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])
Junio C Hamanoccef66b2005-06-07 14:35:43 -070015
David Greaves2cf565c2005-05-10 22:32:30 +010016
17DESCRIPTION
18-----------
Lukas_Sandström5f3aa192005-11-11 02:12:27 +010019Reads the tree information given by <tree-ish> into the index,
David Greavesc1bdacf2005-05-10 22:32:38 +010020but does not actually *update* any of the files it "caches". (see:
Dan McGee5162e692007-12-29 00:20:38 -060021linkgit:git-checkout-index[1])
David Greaves2cf565c2005-05-10 22:32:30 +010022
Lukas_Sandström5f3aa192005-11-11 02:12:27 +010023Optionally, it can merge a tree into the index, perform a
Jon Loeliger61f693b2005-12-05 23:13:03 -060024fast-forward (i.e. 2-way) merge, or a 3-way merge, with the `-m`
25flag. When used with `-m`, the `-u` flag causes it to also update
Junio C Hamanoccef66b2005-06-07 14:35:43 -070026the files in the work tree with the result of the merge.
David Greaves2cf565c2005-05-10 22:32:30 +010027
Thomas Rast0b444cd2010-01-10 00:33:00 +010028Trivial merges are done by 'git read-tree' itself. Only conflicting paths
29will be in unmerged state when 'git read-tree' returns.
David Greaves2cf565c2005-05-10 22:32:30 +010030
31OPTIONS
32-------
33-m::
No name3f41f5a2005-12-02 06:37:13 -050034 Perform a merge, not just a read. The command will
35 refuse to run if your index file has unmerged entries,
36 indicating that you have not finished previous merge you
37 started.
Junio C Hamanoccef66b2005-06-07 14:35:43 -070038
Nikolai Weibull2db0bfb2005-11-15 00:20:01 +010039--reset::
Nguyễn Thái Ngọc Duyb5a0bd62019-04-01 19:05:05 +070040 Same as -m, except that unmerged entries are discarded instead
Elijah Newren0e292222021-09-27 16:33:48 +000041 of failing. When used with `-u`, updates leading to loss of
42 working tree changes or untracked files or directories will not
43 abort the operation.
Nikolai Weibull2db0bfb2005-11-15 00:20:01 +010044
Junio C Hamanoccef66b2005-06-07 14:35:43 -070045-u::
46 After a successful merge, update the files in the work
47 tree with the result of the merge.
David Greaves2cf565c2005-05-10 22:32:30 +010048
Junio C Hamanof318dd22005-09-19 11:33:14 -070049-i::
50 Usually a merge requires the index file as well as the
Michael J Grubercc1a2b62011-09-21 09:48:37 +020051 files in the working tree to be up to date with the
Junio C Hamanof318dd22005-09-19 11:33:14 -070052 current head commit, in order not to lose local
53 changes. This flag disables the check with the working
54 tree and is meant to be used when creating a merge of
55 trees that are not directly related to the current
56 working tree status into a temporary index file.
57
Jens Lehmannea5070c2011-05-25 22:10:41 +020058-n::
59--dry-run::
60 Check if the command would error out, without updating the index
Justin Lebara58088a2014-03-31 15:11:44 -070061 or the files in the working tree for real.
Jens Lehmannea5070c2011-05-25 22:10:41 +020062
Miklos Vajna22e801f2008-06-09 22:25:15 +020063-v::
64 Show the progress of checking files out.
65
Jakub Narebski6da08782007-06-16 21:03:45 +020066--trivial::
Thomas Rast0b444cd2010-01-10 00:33:00 +010067 Restrict three-way merge by 'git read-tree' to happen
Jakub Narebski6da08782007-06-16 21:03:45 +020068 only if there is no file-level merging required, instead
69 of resolving merge for trivial cases and leaving
70 conflicting files unresolved in the index.
71
Junio C Hamanoafaa8d62006-03-02 01:11:05 -080072--aggressive::
Thomas Rast0b444cd2010-01-10 00:33:00 +010073 Usually a three-way merge by 'git read-tree' resolves
Junio C Hamanoafaa8d62006-03-02 01:11:05 -080074 the merge for really trivial cases and leaves other
Michael J Grubercc1a2b62011-09-21 09:48:37 +020075 cases unresolved in the index, so that porcelains can
Junio C Hamanoafaa8d62006-03-02 01:11:05 -080076 implement different merge policies. This flag makes the
Michael J Grubercc1a2b62011-09-21 09:48:37 +020077 command resolve a few more cases internally:
Junio C Hamanoafaa8d62006-03-02 01:11:05 -080078+
79* when one side removes a path and the other side leaves the path
80 unmodified. The resolution is to remove that path.
81* when both sides remove a path. The resolution is to remove that path.
Michael J Grubercc1a2b62011-09-21 09:48:37 +020082* when both sides add a path identically. The resolution
Junio C Hamanoafaa8d62006-03-02 01:11:05 -080083 is to add that path.
84
Andreas G. Schacker30221a32018-01-09 16:30:34 +010085--prefix=<prefix>::
Junio C Hamanof4c6f2d2006-01-14 21:46:58 -080086 Keep the current index contents, and read the contents
Clemens Buchacher5c951ef2011-12-31 12:50:56 +010087 of the named tree-ish under the directory at `<prefix>`.
88 The command will refuse to overwrite entries that already
Andreas G. Schacker30221a32018-01-09 16:30:34 +010089 existed in the original index file.
Junio C Hamanof4c6f2d2006-01-14 21:46:58 -080090
Junio C Hamano5e7f56a2007-03-31 23:27:41 -070091--index-output=<file>::
92 Instead of writing the results out to `$GIT_INDEX_FILE`,
93 write the resulting index in the named file. While the
94 command is operating, the original index file is locked
95 with the same mechanism as usual. The file must allow
96 to be rename(2)ed into from a temporary file that is
97 created next to the usual index file; typically this
98 means it needs to be on the same filesystem as the index
99 file itself, and you need write permission to the
100 directories the index file and index output file are
101 located in.
102
Stefan Beller25804912017-03-14 14:46:42 -0700103--[no-]recurse-submodules::
Damien Robertacbfae32020-04-06 15:57:09 +0200104 Using --recurse-submodules will update the content of all active
Stefan Beller25804912017-03-14 14:46:42 -0700105 submodules according to the commit recorded in the superproject by
Damien Robertb3cec572020-04-06 15:57:06 +0200106 calling read-tree recursively, also setting the submodules' HEAD to be
Stefan Beller25804912017-03-14 14:46:42 -0700107 detached at that commit.
108
Nguyễn Thái Ngọc Duya5d07d02009-08-20 20:47:11 +0700109--no-sparse-checkout::
110 Disable sparse checkout support even if `core.sparseCheckout`
111 is true.
112
Jan Krügerfb1bb962010-09-10 15:28:59 +0200113--empty::
114 Instead of reading tree object(s) into the index, just empty
115 it.
116
Nguyễn Thái Ngọc Duy3e414852019-03-22 16:31:37 +0700117-q::
118--quiet::
119 Quiet, suppress feedback messages.
120
David Greaves2cf565c2005-05-10 22:32:30 +0100121<tree-ish#>::
122 The id of the tree object(s) to be read/merged.
123
124
Nguyễn Thái Ngọc Duy76a87882018-04-30 17:35:33 +0200125MERGING
David Greaves2cf565c2005-05-10 22:32:30 +0100126-------
Thomas Rast0b444cd2010-01-10 00:33:00 +0100127If `-m` is specified, 'git read-tree' can perform 3 kinds of
Junio C Hamanoccef66b2005-06-07 14:35:43 -0700128merge, a single tree merge if only 1 tree is given, a
Jean-Noel Avila99322422017-05-11 14:06:33 +0200129fast-forward merge with 2 trees, or a 3-way merge if 3 or more trees are
David Greaves2cf565c2005-05-10 22:32:30 +0100130provided.
131
Junio C Hamanoccef66b2005-06-07 14:35:43 -0700132
David Greaves2cf565c2005-05-10 22:32:30 +0100133Single Tree Merge
134~~~~~~~~~~~~~~~~~
Thomas Rast0b444cd2010-01-10 00:33:00 +0100135If only 1 tree is specified, 'git read-tree' operates as if the user did not
Jon Loeliger61f693b2005-12-05 23:13:03 -0600136specify `-m`, except that if the original index has an entry for a
Michael J Gruber73252832010-03-15 11:54:46 +0100137given pathname, and the contents of the path match with the tree
Lukas_Sandström5f3aa192005-11-11 02:12:27 +0100138being read, the stat info from the index is used. (In other words, the
139index's stat()s take precedence over the merged tree's).
David Greaves2cf565c2005-05-10 22:32:30 +0100140
Jonathan Niederb1889c32008-06-30 01:09:04 -0500141That means that if you do a `git read-tree -m <newtree>` followed by a
Thomas Rast0b444cd2010-01-10 00:33:00 +0100142`git checkout-index -f -u -a`, the 'git checkout-index' only checks out
David Greaves2cf565c2005-05-10 22:32:30 +0100143the stuff that really changed.
144
Thomas Rast0b444cd2010-01-10 00:33:00 +0100145This is used to avoid unnecessary false hits when 'git diff-files' is
146run after 'git read-tree'.
David Greaves2cf565c2005-05-10 22:32:30 +0100147
Junio C Hamanoc8596002005-06-07 11:36:30 -0700148
149Two Tree Merge
150~~~~~~~~~~~~~~
151
Jonathan Niederb1889c32008-06-30 01:09:04 -0500152Typically, this is invoked as `git read-tree -m $H $M`, where $H
Junio C Hamanoc8596002005-06-07 11:36:30 -0700153is the head commit of the current repository, and $M is the head
154of a foreign tree, which is simply ahead of $H (i.e. we are in a
Felipe Contrerasa75d7b52009-10-24 11:31:32 +0300155fast-forward situation).
Junio C Hamanoc8596002005-06-07 11:36:30 -0700156
Thomas Rast0b444cd2010-01-10 00:33:00 +0100157When two trees are specified, the user is telling 'git read-tree'
Junio C Hamanoc8596002005-06-07 11:36:30 -0700158the following:
159
Jonas Fonsecadf8baa42005-10-03 19:16:30 +0200160 1. The current index and work tree is derived from $H, but
Michael J Gruber73252832010-03-15 11:54:46 +0100161 the user may have local changes in them since $H.
Junio C Hamanoc8596002005-06-07 11:36:30 -0700162
Jonas Fonsecadf8baa42005-10-03 19:16:30 +0200163 2. The user wants to fast-forward to $M.
Junio C Hamanoc8596002005-06-07 11:36:30 -0700164
Jonathan Niederb1889c32008-06-30 01:09:04 -0500165In this case, the `git read-tree -m $H $M` command makes sure
Junio C Hamanoc8596002005-06-07 11:36:30 -0700166that no local change is lost as the result of this "merge".
Michael J Gruber73252832010-03-15 11:54:46 +0100167Here are the "carry forward" rules, where "I" denotes the index,
168"clean" means that index and work tree coincide, and "exists"/"nothing"
169refer to the presence of a path in the specified commit:
Junio C Hamanoc8596002005-06-07 11:36:30 -0700170
Jeff Kingc08fd632017-09-23 01:55:26 -0400171....
Michael J Gruber73252832010-03-15 11:54:46 +0100172 I H M Result
Junio C Hamanoc8596002005-06-07 11:36:30 -0700173 -------------------------------------------------------
Michael J Gruber71928f72010-03-15 11:54:45 +0100174 0 nothing nothing nothing (does not happen)
175 1 nothing nothing exists use M
176 2 nothing exists nothing remove path from index
Michael J Gruber73252832010-03-15 11:54:46 +0100177 3 nothing exists exists, use M if "initial checkout",
Junio C Hamano55218832008-09-07 19:49:25 -0700178 H == M keep index otherwise
Michael J Gruber73252832010-03-15 11:54:46 +0100179 exists, fail
Junio C Hamano55218832008-09-07 19:49:25 -0700180 H != M
Junio C Hamanoc8596002005-06-07 11:36:30 -0700181
182 clean I==H I==M
183 ------------------
Michael J Gruber71928f72010-03-15 11:54:45 +0100184 4 yes N/A N/A nothing nothing keep index
185 5 no N/A N/A nothing nothing keep index
Junio C Hamanoc8596002005-06-07 11:36:30 -0700186
Michael J Gruber71928f72010-03-15 11:54:45 +0100187 6 yes N/A yes nothing exists keep index
188 7 no N/A yes nothing exists keep index
189 8 yes N/A no nothing exists fail
190 9 no N/A no nothing exists fail
Junio C Hamanoc8596002005-06-07 11:36:30 -0700191
Lukas_Sandström5f3aa192005-11-11 02:12:27 +0100192 10 yes yes N/A exists nothing remove path from index
Junio C Hamanoc8596002005-06-07 11:36:30 -0700193 11 no yes N/A exists nothing fail
194 12 yes no N/A exists nothing fail
195 13 no no N/A exists nothing fail
196
Michael J Gruber73252832010-03-15 11:54:46 +0100197 clean (H==M)
Junio C Hamanoc8596002005-06-07 11:36:30 -0700198 ------
199 14 yes exists exists keep index
200 15 no exists exists keep index
201
202 clean I==H I==M (H!=M)
203 ------------------
204 16 yes no no exists exists fail
205 17 no no no exists exists fail
206 18 yes no yes exists exists keep index
207 19 no no yes exists exists keep index
208 20 yes yes no exists exists use M
209 21 no yes no exists exists fail
Jeff Kingc08fd632017-09-23 01:55:26 -0400210....
Junio C Hamanoc8596002005-06-07 11:36:30 -0700211
Lukas_Sandström5f3aa192005-11-11 02:12:27 +0100212In all "keep index" cases, the index entry stays as in the
Michael J Gruber73252832010-03-15 11:54:46 +0100213original index file. If the entry is not up to date,
Thomas Rast0b444cd2010-01-10 00:33:00 +0100214'git read-tree' keeps the copy in the work tree intact when
Junio C Hamanoc8596002005-06-07 11:36:30 -0700215operating under the -u flag.
216
Thomas Rast0b444cd2010-01-10 00:33:00 +0100217When this form of 'git read-tree' returns successfully, you can
Michael J Gruber73252832010-03-15 11:54:46 +0100218see which of the "local changes" that you made were carried forward by running
Jonathan Niederb1889c32008-06-30 01:09:04 -0500219`git diff-index --cached $M`. Note that this does not
Michael J Gruber73252832010-03-15 11:54:46 +0100220necessarily match what `git diff-index --cached $H` would have
Junio C Hamanoc8596002005-06-07 11:36:30 -0700221produced before such a two tree merge. This is because of cases
22218 and 19 --- if you already had the changes in $M (e.g. maybe
Jonathan Niederb1889c32008-06-30 01:09:04 -0500223you picked it up via e-mail in a patch form), `git diff-index
Jon Loeliger61f693b2005-12-05 23:13:03 -0600224--cached $H` would have told you about the change before this
Jonathan Niederb1889c32008-06-30 01:09:04 -0500225merge, but it would not show in `git diff-index --cached $M`
Michael J Gruber73252832010-03-15 11:54:46 +0100226output after the two-tree merge.
Junio C Hamanoc8596002005-06-07 11:36:30 -0700227
Michael J Gruber73252832010-03-15 11:54:46 +0100228Case 3 is slightly tricky and needs explanation. The result from this
Junio C Hamano55218832008-09-07 19:49:25 -0700229rule logically should be to remove the path if the user staged the removal
Ralf Wildenhues79fd4cc2008-09-29 22:30:00 +0200230of the path and then switching to a new branch. That however will prevent
Junio C Hamano55218832008-09-07 19:49:25 -0700231the initial checkout from happening, so the rule is modified to use M (new
Michael J Gruber73252832010-03-15 11:54:46 +0100232tree) only when the content of the index is empty. Otherwise the removal
Junio C Hamano55218832008-09-07 19:49:25 -0700233of the path is kept as long as $H and $M are the same.
Junio C Hamanoc8596002005-06-07 11:36:30 -0700234
David Greaves2cf565c2005-05-10 22:32:30 +01002353-Way Merge
236~~~~~~~~~~~
237Each "index" entry has two bits worth of "stage" state. stage 0 is the
238normal one, and is the only one you'd see in any kind of normal use.
239
Thomas Rast0b444cd2010-01-10 00:33:00 +0100240However, when you do 'git read-tree' with three trees, the "stage"
David Greaves2cf565c2005-05-10 22:32:30 +0100241starts out at 1.
242
243This means that you can do
244
Jon Loeliger61f693b2005-12-05 23:13:03 -0600245----------------
Jonathan Niederb1889c32008-06-30 01:09:04 -0500246$ git read-tree -m <tree1> <tree2> <tree3>
Jon Loeliger61f693b2005-12-05 23:13:03 -0600247----------------
David Greaves2cf565c2005-05-10 22:32:30 +0100248
249and you will end up with an index with all of the <tree1> entries in
250"stage1", all of the <tree2> entries in "stage2" and all of the
Junio C Hamanobb6d7b82005-12-05 23:26:10 -0800251<tree3> entries in "stage3". When performing a merge of another
252branch into the current branch, we use the common ancestor tree
253as <tree1>, the current branch head as <tree2>, and the other
254branch head as <tree3>.
David Greaves2cf565c2005-05-10 22:32:30 +0100255
Thomas Rast0b444cd2010-01-10 00:33:00 +0100256Furthermore, 'git read-tree' has special-case logic that says: if you see
David Greaves2cf565c2005-05-10 22:32:30 +0100257a file that matches in all respects in the following states, it
258"collapses" back to "stage0":
259
260 - stage 2 and 3 are the same; take one or the other (it makes no
Junio C Hamanobb6d7b82005-12-05 23:26:10 -0800261 difference - the same work has been done on our branch in
262 stage 2 and their branch in stage 3)
David Greaves2cf565c2005-05-10 22:32:30 +0100263
264 - stage 1 and stage 2 are the same and stage 3 is different; take
Junio C Hamanobb6d7b82005-12-05 23:26:10 -0800265 stage 3 (our branch in stage 2 did not do anything since the
266 ancestor in stage 1 while their branch in stage 3 worked on
267 it)
David Greaves2cf565c2005-05-10 22:32:30 +0100268
269 - stage 1 and stage 3 are the same and stage 2 is different take
Junio C Hamanobb6d7b82005-12-05 23:26:10 -0800270 stage 2 (we did something while they did nothing)
David Greaves2cf565c2005-05-10 22:32:30 +0100271
Thomas Rast0b444cd2010-01-10 00:33:00 +0100272The 'git write-tree' command refuses to write a nonsensical tree, and it
David Greaves2cf565c2005-05-10 22:32:30 +0100273will complain about unmerged entries if it sees a single entry that is not
274stage 0.
275
Horst H. von Brandabda1ef2006-06-03 16:27:26 -0400276OK, this all sounds like a collection of totally nonsensical rules,
David Greaves2cf565c2005-05-10 22:32:30 +0100277but it's actually exactly what you want in order to do a fast
278merge. The different stages represent the "result tree" (stage 0, aka
279"merged"), the original tree (stage 1, aka "orig"), and the two trees
280you are trying to merge (stage 2 and 3 respectively).
281
Junio C Hamanoccef66b2005-06-07 14:35:43 -0700282The order of stages 1, 2 and 3 (hence the order of three
Jason St. John06ab60c2014-05-21 14:52:26 -0400283<tree-ish> command-line arguments) are significant when you
Junio C Hamanoccef66b2005-06-07 14:35:43 -0700284start a 3-way merge with an index file that is already
285populated. Here is an outline of how the algorithm works:
David Greaves2cf565c2005-05-10 22:32:30 +0100286
287- if a file exists in identical format in all three trees, it will
Thomas Rast0b444cd2010-01-10 00:33:00 +0100288 automatically collapse to "merged" state by 'git read-tree'.
David Greaves2cf565c2005-05-10 22:32:30 +0100289
290- a file that has _any_ difference what-so-ever in the three trees
Johannes Schindelin2c6e4772005-08-05 17:05:02 +0200291 will stay as separate entries in the index. It's up to "porcelain
David Greaves2cf565c2005-05-10 22:32:30 +0100292 policy" to determine how to remove the non-0 stages, and insert a
Junio C Hamanoccef66b2005-06-07 14:35:43 -0700293 merged version.
David Greaves2cf565c2005-05-10 22:32:30 +0100294
295- the index file saves and restores with all this information, so you
296 can merge things incrementally, but as long as it has entries in
Horst H. von Brandabda1ef2006-06-03 16:27:26 -0400297 stages 1/2/3 (i.e., "unmerged entries") you can't write the result. So
David Greaves2cf565c2005-05-10 22:32:30 +0100298 now the merge algorithm ends up being really simple:
299
300 * you walk the index in order, and ignore all entries of stage 0,
301 since they've already been done.
302
303 * if you find a "stage1", but no matching "stage2" or "stage3", you
304 know it's been removed from both trees (it only existed in the
305 original tree), and you remove that entry.
306
307 * if you find a matching "stage2" and "stage3" tree, you remove one
308 of them, and turn the other into a "stage0" entry. Remove any
309 matching "stage1" entry if it exists too. .. all the normal
310 trivial rules ..
311
Thomas Rast0b444cd2010-01-10 00:33:00 +0100312You would normally use 'git merge-index' with supplied
313'git merge-one-file' to do this last step. The script updates
Junio C Hamanobb6d7b82005-12-05 23:26:10 -0800314the files in the working tree as it merges each path and at the
315end of a successful merge.
Junio C Hamanoccef66b2005-06-07 14:35:43 -0700316
317When you start a 3-way merge with an index file that is already
318populated, it is assumed that it represents the state of the
319files in your work tree, and you can even have files with
320changes unrecorded in the index file. It is further assumed
321that this state is "derived" from the stage 2 tree. The 3-way
322merge refuses to run if it finds an entry in the original index
323file that does not match stage 2.
324
325This is done to prevent you from losing your work-in-progress
Junio C Hamanobb6d7b82005-12-05 23:26:10 -0800326changes, and mixing your random changes in an unrelated merge
327commit. To illustrate, suppose you start from what has been
Francis Daly37425062006-06-07 13:56:45 +0100328committed last to your repository:
Junio C Hamanoccef66b2005-06-07 14:35:43 -0700329
Jon Loeliger61f693b2005-12-05 23:13:03 -0600330----------------
Jonathan Niederb1889c32008-06-30 01:09:04 -0500331$ JC=`git rev-parse --verify "HEAD^0"`
332$ git checkout-index -f -u -a $JC
Jon Loeliger61f693b2005-12-05 23:13:03 -0600333----------------
Junio C Hamanoccef66b2005-06-07 14:35:43 -0700334
Thomas Rast0b444cd2010-01-10 00:33:00 +0100335You do random edits, without running 'git update-index'. And then
Junio C Hamanoccef66b2005-06-07 14:35:43 -0700336you notice that the tip of your "upstream" tree has advanced
337since you pulled from him:
338
Jon Loeliger61f693b2005-12-05 23:13:03 -0600339----------------
Jonathan Niederb1889c32008-06-30 01:09:04 -0500340$ git fetch git://.... linus
Joey Hess96890f42011-12-26 12:16:56 -0400341$ LT=`git rev-parse FETCH_HEAD`
Jon Loeliger61f693b2005-12-05 23:13:03 -0600342----------------
Junio C Hamanoccef66b2005-06-07 14:35:43 -0700343
344Your work tree is still based on your HEAD ($JC), but you have
345some edits since. Three-way merge makes sure that you have not
Lukas_Sandström5f3aa192005-11-11 02:12:27 +0100346added or modified index entries since $JC, and if you haven't,
Junio C Hamanoccef66b2005-06-07 14:35:43 -0700347then does the right thing. So with the following sequence:
348
Jon Loeliger61f693b2005-12-05 23:13:03 -0600349----------------
Jonathan Niederb1889c32008-06-30 01:09:04 -0500350$ git read-tree -m -u `git merge-base $JC $LT` $JC $LT
351$ git merge-index git-merge-one-file -a
Jon Loeliger61f693b2005-12-05 23:13:03 -0600352$ echo "Merge with Linus" | \
Jonathan Niederb1889c32008-06-30 01:09:04 -0500353 git commit-tree `git write-tree` -p $JC -p $LT
Jon Loeliger61f693b2005-12-05 23:13:03 -0600354----------------
Junio C Hamanoccef66b2005-06-07 14:35:43 -0700355
Jon Loeliger61f693b2005-12-05 23:13:03 -0600356what you would commit is a pure merge between $JC and $LT without
Junio C Hamanoccef66b2005-06-07 14:35:43 -0700357your work-in-progress changes, and your work tree would be
358updated to the result of the merge.
359
Junio C Hamanobb6d7b82005-12-05 23:26:10 -0800360However, if you have local changes in the working tree that
Thomas Rast0b444cd2010-01-10 00:33:00 +0100361would be overwritten by this merge, 'git read-tree' will refuse
Junio C Hamanobb6d7b82005-12-05 23:26:10 -0800362to run to prevent your changes from being lost.
363
364In other words, there is no need to worry about what exists only
365in the working tree. When you have local changes in a part of
366the project that is not involved in the merge, your changes do
367not interfere with the merge, and are kept intact. When they
Thomas Rast0b444cd2010-01-10 00:33:00 +0100368*do* interfere, the merge does not even start ('git read-tree'
Junio C Hamanobb6d7b82005-12-05 23:26:10 -0800369complains loudly and fails without modifying anything). In such
370a case, you can simply continue doing what you were in the
371middle of doing, and when your working tree is ready (i.e. you
372have finished your work-in-progress), attempt the merge again.
373
David Greaves2cf565c2005-05-10 22:32:30 +0100374
Nguyễn Thái Ngọc Duy76a87882018-04-30 17:35:33 +0200375SPARSE CHECKOUT
Nguyễn Thái Ngọc Duyed5336a2009-08-20 20:47:05 +0700376---------------
377
Elijah Newren5d4b2932022-04-22 02:32:26 +0000378Note: The skip-worktree capabilities in linkgit:git-update-index[1]
379and `read-tree` predated the introduction of
380linkgit:git-sparse-checkout[1]. Users are encouraged to use the
381`sparse-checkout` command in preference to these plumbing commands for
382sparse-checkout/skip-worktree related needs. However, the information
383below might be useful to users trying to understand the pattern style
384used in non-cone mode of the `sparse-checkout` command.
Elijah Newren90235352022-01-14 15:59:42 +0000385
Michael J Grubercc1a2b62011-09-21 09:48:37 +0200386"Sparse checkout" allows populating the working directory sparsely.
Elijah Newren90235352022-01-14 15:59:42 +0000387It uses the skip-worktree bit (see linkgit:git-update-index[1]) to
388tell Git whether a file in the working directory is worth looking at.
Nguyễn Thái Ngọc Duyed5336a2009-08-20 20:47:05 +0700389
Michael J Grubercc1a2b62011-09-21 09:48:37 +0200390'git read-tree' and other merge-based commands ('git merge', 'git
391checkout'...) can help maintaining the skip-worktree bitmap and working
Nguyễn Thái Ngọc Duyed5336a2009-08-20 20:47:05 +0700392directory update. `$GIT_DIR/info/sparse-checkout` is used to
Michael J Grubercc1a2b62011-09-21 09:48:37 +0200393define the skip-worktree reference bitmap. When 'git read-tree' needs
394to update the working directory, it resets the skip-worktree bit in the index
Nguyễn Thái Ngọc Duyed5336a2009-08-20 20:47:05 +0700395based on this file, which uses the same syntax as .gitignore files.
Elijah Newren90235352022-01-14 15:59:42 +0000396If an entry matches a pattern in this file, or the entry corresponds to
397a file present in the working tree, then skip-worktree will not be
Michael J Gruber1f1f5752011-09-21 09:48:38 +0200398set on that entry. Otherwise, skip-worktree will be set.
Nguyễn Thái Ngọc Duyed5336a2009-08-20 20:47:05 +0700399
400Then it compares the new skip-worktree value with the previous one. If
Michael J Gruber1f1f5752011-09-21 09:48:38 +0200401skip-worktree turns from set to unset, it will add the corresponding
402file back. If it turns from unset to set, that file will be removed.
Nguyễn Thái Ngọc Duyed5336a2009-08-20 20:47:05 +0700403
404While `$GIT_DIR/info/sparse-checkout` is usually used to specify what
Michael J Grubercc1a2b62011-09-21 09:48:37 +0200405files are in, you can also specify what files are _not_ in, using
406negate patterns. For example, to remove the file `unwanted`:
Nguyễn Thái Ngọc Duyed5336a2009-08-20 20:47:05 +0700407
408----------------
Nguyễn Thái Ngọc Duy5e821232011-09-26 09:09:15 +1000409/*
Nguyễn Thái Ngọc Duyed5336a2009-08-20 20:47:05 +0700410!unwanted
411----------------
412
Michael J Grubercc1a2b62011-09-21 09:48:37 +0200413Another tricky thing is fully repopulating the working directory when you
Nguyễn Thái Ngọc Duyed5336a2009-08-20 20:47:05 +0700414no longer want sparse checkout. You cannot just disable "sparse
Michael J Grubercc1a2b62011-09-21 09:48:37 +0200415checkout" because skip-worktree bits are still in the index and your working
416directory is still sparsely populated. You should re-populate the working
Nguyễn Thái Ngọc Duyed5336a2009-08-20 20:47:05 +0700417directory with the `$GIT_DIR/info/sparse-checkout` file content as
418follows:
419
420----------------
Nguyễn Thái Ngọc Duy5e821232011-09-26 09:09:15 +1000421/*
Nguyễn Thái Ngọc Duyed5336a2009-08-20 20:47:05 +0700422----------------
423
Michael J Grubercc1a2b62011-09-21 09:48:37 +0200424Then you can disable sparse checkout. Sparse checkout support in 'git
425read-tree' and similar commands is disabled by default. You need to
Nguyễn Thái Ngọc Duy08aefc92009-08-20 20:47:08 +0700426turn `core.sparseCheckout` on in order to have sparse checkout
427support.
Nguyễn Thái Ngọc Duyed5336a2009-08-20 20:47:05 +0700428
429
Junio C Hamano56ae8df2008-05-28 16:55:27 -0700430SEE ALSO
David Greavesc1bdacf2005-05-10 22:32:38 +0100431--------
Nihal Jere63a36012022-03-03 10:15:43 -0600432linkgit:git-write-tree[1], linkgit:git-ls-files[1],
433linkgit:gitignore[5], linkgit:git-sparse-checkout[1]
David Greaves2cf565c2005-05-10 22:32:30 +0100434
David Greaves2cf565c2005-05-10 22:32:30 +0100435GIT
436---
Christian Couder9e1f0a82008-06-06 09:07:32 +0200437Part of the linkgit:git[1] suite