freshlybakedca.ke
Git fork
1git-read-tree(1)
2================
3
4NAME
5----
6git-read-tree - Reads tree information into the index
7
8
9SYNOPSIS
10--------
11[verse]
12'git read-tree' [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)
13 [-u | -i]] [--index-output=<file>] [--no-sparse-checkout]
14 (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])
15
16
17DESCRIPTION
18-----------
19Reads the tree information given by <tree-ish> into the index,
20but does not actually *update* any of the files it "caches". (see:
21linkgit:git-checkout-index[1])
22
23Optionally, it can merge a tree into the index, perform a
24fast-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
26the files in the work tree with the result of the merge.
27
28Only trivial merges are done by 'git read-tree' itself. Only conflicting paths
29will be in an unmerged state when 'git read-tree' returns.
30
31OPTIONS
32-------
33-m::
34 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 a previous merge you
37 started.
38
39--reset::
40 Same as -m, except that unmerged entries are discarded instead
41 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.
44
45-u::
46 After a successful merge, update the files in the work
47 tree with the result of the merge.
48
49-i::
50 Usually a merge requires the index file as well as the
51 files in the working tree to be up to date with the
52 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
58-n::
59--dry-run::
60 Check if the command would error out, without updating the index
61 or the files in the working tree for real.
62
63-v::
64 Show the progress of checking files out.
65
66--trivial::
67 Restrict three-way merge by 'git read-tree' to happen
68 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
72--aggressive::
73 Usually a three-way merge by 'git read-tree' resolves
74 the merge for really trivial cases and leaves other
75 cases unresolved in the index, so that porcelains can
76 implement different merge policies. This flag makes the
77 command resolve a few more cases internally:
78+
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.
82* when both sides add a path identically. The resolution
83 is to add that path.
84
85--prefix=<prefix>::
86 Keep the current index contents, and read the contents
87 of the named tree-ish under the directory at `<prefix>`.
88 The command will refuse to overwrite entries that already
89 existed in the original index file.
90
91--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
103--recurse-submodules::
104--no-recurse-submodules::
105 Using --recurse-submodules will update the content of all active
106 submodules according to the commit recorded in the superproject by
107 calling read-tree recursively, also setting the submodules' HEAD to be
108 detached at that commit.
109
110--no-sparse-checkout::
111 Disable sparse checkout support even if `core.sparseCheckout`
112 is true.
113
114--empty::
115 Instead of reading tree object(s) into the index, just empty
116 it.
117
118-q::
119--quiet::
120 Quiet, suppress feedback messages.
121
122<tree-ish#>::
123 The id of the tree object(s) to be read/merged.
124
125
126MERGING
127-------
128If `-m` is specified, 'git read-tree' can perform 3 kinds of
129merge, a single tree merge if only 1 tree is given, a
130fast-forward merge with 2 trees, or a 3-way merge if 3 or more trees are
131provided.
132
133
134Single Tree Merge
135~~~~~~~~~~~~~~~~~
136If only 1 tree is specified, 'git read-tree' operates as if the user did not
137specify `-m`, except that if the original index has an entry for a
138given pathname, and the contents of the path match with the tree
139being read, the stat info from the index is used. (In other words, the
140index's stat()s take precedence over the merged tree's).
141
142That means that if you do a `git read-tree -m <newtree>` followed by a
143`git checkout-index -f -u -a`, the 'git checkout-index' only checks out
144the stuff that really changed.
145
146This is used to avoid unnecessary false hits when 'git diff-files' is
147run after 'git read-tree'.
148
149
150Two Tree Merge
151~~~~~~~~~~~~~~
152
153Typically, this is invoked as `git read-tree -m $H $M`, where $H
154is the head commit of the current repository, and $M is the head
155of a foreign tree, which is simply ahead of $H (i.e. we are in a
156fast-forward situation).
157
158When two trees are specified, the user is telling 'git read-tree'
159the following:
160
161 1. The current index and work tree is derived from $H, but
162 the user may have local changes in them since $H.
163
164 2. The user wants to fast-forward to $M.
165
166In this case, the `git read-tree -m $H $M` command makes sure
167that no local change is lost as the result of this "merge".
168Here are the "carry forward" rules, where "I" denotes the index,
169"clean" means that index and work tree coincide, and "exists"/"nothing"
170refer to the presence of a path in the specified commit:
171
172....
173 I H M Result
174 -------------------------------------------------------
175 0 nothing nothing nothing (does not happen)
176 1 nothing nothing exists use M
177 2 nothing exists nothing remove path from index
178 3 nothing exists exists, use M if "initial checkout",
179 H == M keep index otherwise
180 exists, fail
181 H != M
182
183 clean I==H I==M
184 ------------------
185 4 yes N/A N/A nothing nothing keep index
186 5 no N/A N/A nothing nothing keep index
187
188 6 yes N/A yes nothing exists keep index
189 7 no N/A yes nothing exists keep index
190 8 yes N/A no nothing exists fail
191 9 no N/A no nothing exists fail
192
193 10 yes yes N/A exists nothing remove path from index
194 11 no yes N/A exists nothing fail
195 12 yes no N/A exists nothing fail
196 13 no no N/A exists nothing fail
197
198 clean (H==M)
199 ------
200 14 yes exists exists keep index
201 15 no exists exists keep index
202
203 clean I==H I==M (H!=M)
204 ------------------
205 16 yes no no exists exists fail
206 17 no no no exists exists fail
207 18 yes no yes exists exists keep index
208 19 no no yes exists exists keep index
209 20 yes yes no exists exists use M
210 21 no yes no exists exists fail
211....
212
213In all "keep index" cases, the index entry stays as in the
214original index file. If the entry is not up to date,
215'git read-tree' keeps the copy in the work tree intact when
216operating under the -u flag.
217
218When this form of 'git read-tree' returns successfully, you can
219see which of the "local changes" that you made were carried forward by running
220`git diff-index --cached $M`. Note that this does not
221necessarily match what `git diff-index --cached $H` would have
222produced before such a two tree merge. This is because of cases
22318 and 19 -- if you already had the changes in $M (e.g. maybe
224you picked it up via e-mail in a patch form), `git diff-index
225--cached $H` would have told you about the change before this
226merge, but it would not show in `git diff-index --cached $M`
227output after the two-tree merge.
228
229Case 3 is slightly tricky and needs explanation. The result from this
230rule logically should be to remove the path if the user staged the removal
231of the path and then switching to a new branch. That however will prevent
232the initial checkout from happening, so the rule is modified to use M (new
233tree) only when the content of the index is empty. Otherwise the removal
234of the path is kept as long as $H and $M are the same.
235
2363-Way Merge
237~~~~~~~~~~~
238Each "index" entry has two bits worth of "stage" state. stage 0 is the
239normal one, and is the only one you'd see in any kind of normal use.
240
241However, when you do 'git read-tree' with three trees, the "stage"
242starts out at 1.
243
244This means that you can do
245
246----------------
247$ git read-tree -m <tree1> <tree2> <tree3>
248----------------
249
250and you will end up with an index with all of the <tree1> entries in
251"stage1", all of the <tree2> entries in "stage2" and all of the
252<tree3> entries in "stage3". When performing a merge of another
253branch into the current branch, we use the common ancestor tree
254as <tree1>, the current branch head as <tree2>, and the other
255branch head as <tree3>.
256
257Furthermore, 'git read-tree' has special-case logic that says: if you see
258a file that matches in all respects in the following states, it
259"collapses" back to "stage0":
260
261 - stage 2 and 3 are the same; take one or the other (it makes no
262 difference - the same work has been done on our branch in
263 stage 2 and their branch in stage 3)
264
265 - stage 1 and stage 2 are the same and stage 3 is different; take
266 stage 3 (our branch in stage 2 did not do anything since the
267 ancestor in stage 1 while their branch in stage 3 worked on
268 it)
269
270 - stage 1 and stage 3 are the same and stage 2 is different take
271 stage 2 (we did something while they did nothing)
272
273The 'git write-tree' command refuses to write a nonsensical tree, and it
274will complain about unmerged entries if it sees a single entry that is not
275stage 0.
276
277OK, this all sounds like a collection of totally nonsensical rules,
278but it's actually exactly what you want in order to do a fast
279merge. The different stages represent the "result tree" (stage 0, aka
280"merged"), the original tree (stage 1, aka "orig"), and the two trees
281you are trying to merge (stage 2 and 3 respectively).
282
283The order of stages 1, 2 and 3 (hence the order of three
284<tree-ish> command-line arguments) are significant when you
285start a 3-way merge with an index file that is already
286populated. Here is an outline of how the algorithm works:
287
288- if a file exists in identical format in all three trees, it will
289 automatically collapse to "merged" state by 'git read-tree'.
290
291- a file that has _any_ difference what-so-ever in the three trees
292 will stay as separate entries in the index. It's up to "porcelain
293 policy" to determine how to remove the non-0 stages, and insert a
294 merged version.
295
296- the index file saves and restores with all this information, so you
297 can merge things incrementally, but as long as it has entries in
298 stages 1/2/3 (i.e., "unmerged entries") you can't write the result. So
299 now the merge algorithm ends up being really simple:
300
301 * you walk the index in order, and ignore all entries of stage 0,
302 since they've already been done.
303
304 * if you find a "stage1", but no matching "stage2" or "stage3", you
305 know it's been removed from both trees (it only existed in the
306 original tree), and you remove that entry.
307
308 * if you find a matching "stage2" and "stage3" tree, you remove one
309 of them, and turn the other into a "stage0" entry. Remove any
310 matching "stage1" entry if it exists too. .. all the normal
311 trivial rules ..
312
313You would normally use 'git merge-index' with supplied
314'git merge-one-file' to do this last step. The script updates
315the files in the working tree as it merges each path and at the
316end of a successful merge.
317
318When you start a 3-way merge with an index file that is already
319populated, it is assumed that it represents the state of the
320files in your work tree, and you can even have files with
321changes unrecorded in the index file. It is further assumed
322that this state is "derived" from the stage 2 tree. The 3-way
323merge refuses to run if it finds an entry in the original index
324file that does not match stage 2.
325
326This is done to prevent you from losing your work-in-progress
327changes, and mixing your random changes in an unrelated merge
328commit. To illustrate, suppose you start from what has been
329committed last to your repository:
330
331----------------
332$ JC=`git rev-parse --verify "HEAD^0"`
333$ git checkout-index -f -u -a $JC
334----------------
335
336You do random edits, without running 'git update-index'. And then
337you notice that the tip of your "upstream" tree has advanced
338since you pulled from him:
339
340----------------
341$ git fetch git://.... linus
342$ LT=`git rev-parse FETCH_HEAD`
343----------------
344
345Your work tree is still based on your HEAD ($JC), but you have
346some edits since. Three-way merge makes sure that you have not
347added or modified index entries since $JC, and if you haven't,
348then does the right thing. So with the following sequence:
349
350----------------
351$ git read-tree -m -u `git merge-base $JC $LT` $JC $LT
352$ git merge-index git-merge-one-file -a
353$ echo "Merge with Linus" | \
354 git commit-tree `git write-tree` -p $JC -p $LT
355----------------
356
357what you would commit is a pure merge between $JC and $LT without
358your work-in-progress changes, and your work tree would be
359updated to the result of the merge.
360
361However, if you have local changes in the working tree that
362would be overwritten by this merge, 'git read-tree' will refuse
363to run to prevent your changes from being lost.
364
365In other words, there is no need to worry about what exists only
366in the working tree. When you have local changes in a part of
367the project that is not involved in the merge, your changes do
368not interfere with the merge, and are kept intact. When they
369*do* interfere, the merge does not even start ('git read-tree'
370complains loudly and fails without modifying anything). In such
371a case, you can simply continue doing what you were in the
372middle of doing, and when your working tree is ready (i.e. you
373have finished your work-in-progress), attempt the merge again.
374
375
376SPARSE CHECKOUT
377---------------
378
379Note: The skip-worktree capabilities in linkgit:git-update-index[1]
380and `read-tree` predated the introduction of
381linkgit:git-sparse-checkout[1]. Users are encouraged to use the
382`sparse-checkout` command in preference to these plumbing commands for
383sparse-checkout/skip-worktree related needs. However, the information
384below might be useful to users trying to understand the pattern style
385used in non-cone mode of the `sparse-checkout` command.
386
387"Sparse checkout" allows populating the working directory sparsely.
388It uses the skip-worktree bit (see linkgit:git-update-index[1]) to
389tell Git whether a file in the working directory is worth looking at.
390
391'git read-tree' and other merge-based commands ('git merge', 'git
392checkout'...) can help maintaining the skip-worktree bitmap and working
393directory update. `$GIT_DIR/info/sparse-checkout` is used to
394define the skip-worktree reference bitmap. When 'git read-tree' needs
395to update the working directory, it resets the skip-worktree bit in the index
396based on this file, which uses the same syntax as .gitignore files.
397If an entry matches a pattern in this file, or the entry corresponds to
398a file present in the working tree, then skip-worktree will not be
399set on that entry. Otherwise, skip-worktree will be set.
400
401Then it compares the new skip-worktree value with the previous one. If
402skip-worktree turns from set to unset, it will add the corresponding
403file back. If it turns from unset to set, that file will be removed.
404
405While `$GIT_DIR/info/sparse-checkout` is usually used to specify what
406files are in, you can also specify what files are _not_ in, using
407negate patterns. For example, to remove the file `unwanted`:
408
409----------------
410/*
411!unwanted
412----------------
413
414Another tricky thing is fully repopulating the working directory when you
415no longer want sparse checkout. You cannot just disable "sparse
416checkout" because skip-worktree bits are still in the index and your working
417directory is still sparsely populated. You should re-populate the working
418directory with the `$GIT_DIR/info/sparse-checkout` file content as
419follows:
420
421----------------
422/*
423----------------
424
425Then you can disable sparse checkout. Sparse checkout support in 'git
426read-tree' and similar commands is disabled by default. You need to
427turn `core.sparseCheckout` on in order to have sparse checkout
428support.
429
430
431SEE ALSO
432--------
433linkgit:git-write-tree[1], linkgit:git-ls-files[1],
434linkgit:gitignore[5], linkgit:git-sparse-checkout[1]
435
436GIT
437---
438Part of the linkgit:git[1] suite