mirror of
https://git.proxmox.com/git/libgit2
synced 2025-05-01 18:47:31 +00:00
205 lines
12 KiB
Markdown
205 lines
12 KiB
Markdown
Checkout Internals
|
|
==================
|
|
|
|
Checkout has to handle a lot of different cases. It examines the
|
|
differences between the target tree, the baseline tree and the working
|
|
directory, plus the contents of the index, and groups files into five
|
|
categories:
|
|
|
|
1. UNMODIFIED - Files that match in all places.
|
|
2. SAFE - Files where the working directory and the baseline content
|
|
match that can be safely updated to the target.
|
|
3. DIRTY/MISSING - Files where the working directory differs from the
|
|
baseline but there is no conflicting change with the target. One
|
|
example is a file that doesn't exist in the working directory - no
|
|
data would be lost as a result of writing this file. Which action
|
|
will be taken with these files depends on the options you use.
|
|
4. CONFLICTS - Files where changes in the working directory conflict
|
|
with changes to be applied by the target. If conflicts are found,
|
|
they prevent any other modifications from being made (although there
|
|
are options to override that and force the update, of course).
|
|
5. UNTRACKED/IGNORED - Files in the working directory that are untracked
|
|
or ignored (i.e. only in the working directory, not the other places).
|
|
|
|
Right now, this classification is done via 3 iterators (for the three
|
|
trees), with a final lookup in the index. At some point, this may move to
|
|
a 4 iterator version to incorporate the index better.
|
|
|
|
The actual checkout is done in five phases (at least right now).
|
|
|
|
1. The diff between the baseline and the target tree is used as a base
|
|
list of possible updates to be applied.
|
|
2. Iterate through the diff and the working directory, building a list of
|
|
actions to be taken (and sending notifications about conflicts and
|
|
dirty files).
|
|
3. Remove any files / directories as needed (because alphabetical
|
|
iteration means that an untracked directory will end up sorted *after*
|
|
a blob that should be checked out with the same name).
|
|
4. Update all blobs.
|
|
5. Update all submodules (after 4 in case a new .gitmodules blob was
|
|
checked out)
|
|
|
|
Checkout could be driven either off a target-to-workdir diff or a
|
|
baseline-to-target diff. There are pros and cons of each.
|
|
|
|
Target-to-workdir means the diff includes every file that could be
|
|
modified, which simplifies bookkeeping, but the code to constantly refer
|
|
back to the baseline gets complicated.
|
|
|
|
Baseline-to-target has simpler code because the diff defines the action to
|
|
take, but needs special handling for untracked and ignored files, if they
|
|
need to be removed.
|
|
|
|
The current checkout implementation is based on a baseline-to-target diff.
|
|
|
|
|
|
Picking Actions
|
|
===============
|
|
|
|
The most interesting aspect of this is phase 2, picking the actions that
|
|
should be taken. There are a lot of corner cases, so it may be easier to
|
|
start by looking at the rules for a simple 2-iterator diff:
|
|
|
|
Key
|
|
---
|
|
- B1,B2,B3 - blobs with different SHAs,
|
|
- Bi - ignored blob (WD only)
|
|
- T1,T2,T3 - trees with different SHAs,
|
|
- Ti - ignored tree (WD only)
|
|
- x - nothing
|
|
|
|
Diff with 2 non-workdir iterators
|
|
---------------------------------
|
|
|
|
| | Old | New | |
|
|
|----|-----|-----|------------------------------------------------------------|
|
|
| 0 | x | x | nothing |
|
|
| 1 | x | B1 | added blob |
|
|
| 2 | x | T1 | added tree |
|
|
| 3 | B1 | x | removed blob |
|
|
| 4 | B1 | B1 | unmodified blob |
|
|
| 5 | B1 | B2 | modified blob |
|
|
| 6 | B1 | T1 | typechange blob -> tree |
|
|
| 7 | T1 | x | removed tree |
|
|
| 8 | T1 | B1 | typechange tree -> blob |
|
|
| 9 | T1 | T1 | unmodified tree |
|
|
| 10 | T1 | T2 | modified tree (implies modified/added/removed blob inside) |
|
|
|
|
|
|
Now, let's make the "New" iterator into a working directory iterator, so
|
|
we replace "added" items with either untracked or ignored, like this:
|
|
|
|
Diff with non-work & workdir iterators
|
|
--------------------------------------
|
|
|
|
| | Old | New | |
|
|
|----|-----|-----|------------------------------------------------------------|
|
|
| 0 | x | x | nothing |
|
|
| 1 | x | B1 | untracked blob |
|
|
| 2 | x | Bi | ignored file |
|
|
| 3 | x | T1 | untracked tree |
|
|
| 4 | x | Ti | ignored tree |
|
|
| 5 | B1 | x | removed blob |
|
|
| 6 | B1 | B1 | unmodified blob |
|
|
| 7 | B1 | B2 | modified blob |
|
|
| 8 | B1 | T1 | typechange blob -> tree |
|
|
| 9 | B1 | Ti | removed blob AND ignored tree as separate items |
|
|
| 10 | T1 | x | removed tree |
|
|
| 11 | T1 | B1 | typechange tree -> blob |
|
|
| 12 | T1 | Bi | removed tree AND ignored blob as separate items |
|
|
| 13 | T1 | T1 | unmodified tree |
|
|
| 14 | T1 | T2 | modified tree (implies modified/added/removed blob inside) |
|
|
|
|
Note: if there is a corresponding entry in the old tree, then a working
|
|
directory item won't be ignored (i.e. no Bi or Ti for tracked items).
|
|
|
|
|
|
Now, expand this to three iterators: a baseline tree, a target tree, and
|
|
an actual working directory tree:
|
|
|
|
Checkout From 3 Iterators (2 not workdir, 1 workdir)
|
|
----------------------------------------------------
|
|
|
|
(base == old HEAD; target == what to checkout; actual == working dir)
|
|
|
|
| |base | target | actual/workdir | |
|
|
|-----|-----|------- |----------------|--------------------------------------------------------------------|
|
|
| 0 | x | x | x | nothing |
|
|
| 1 | x | x | B1/Bi/T1/Ti | untracked/ignored blob/tree (SAFE) |
|
|
| 2+ | x | B1 | x | add blob (SAFE) |
|
|
| 3 | x | B1 | B1 | independently added blob (FORCEABLE-2) |
|
|
| 4* | x | B1 | B2/Bi/T1/Ti | add blob with content conflict (FORCEABLE-2) |
|
|
| 5+ | x | T1 | x | add tree (SAFE) |
|
|
| 6* | x | T1 | B1/Bi | add tree with blob conflict (FORCEABLE-2) |
|
|
| 7 | x | T1 | T1/i | independently added tree (SAFE+MISSING) |
|
|
| 8 | B1 | x | x | independently deleted blob (SAFE+MISSING) |
|
|
| 9- | B1 | x | B1 | delete blob (SAFE) |
|
|
| 10- | B1 | x | B2 | delete of modified blob (FORCEABLE-1) |
|
|
| 11 | B1 | x | T1/Ti | independently deleted blob AND untrack/ign tree (SAFE+MISSING !!!) |
|
|
| 12 | B1 | B1 | x | locally deleted blob (DIRTY || SAFE+CREATE) |
|
|
| 13+ | B1 | B2 | x | update to deleted blob (SAFE+MISSING) |
|
|
| 14 | B1 | B1 | B1 | unmodified file (SAFE) |
|
|
| 15 | B1 | B1 | B2 | locally modified file (DIRTY) |
|
|
| 16+ | B1 | B2 | B1 | update unmodified blob (SAFE) |
|
|
| 17 | B1 | B2 | B2 | independently updated blob (FORCEABLE-1) |
|
|
| 18+ | B1 | B2 | B3 | update to modified blob (FORCEABLE-1) |
|
|
| 19 | B1 | B1 | T1/Ti | locally deleted blob AND untrack/ign tree (DIRTY) |
|
|
| 20* | B1 | B2 | T1/Ti | update to deleted blob AND untrack/ign tree (F-1) |
|
|
| 21+ | B1 | T1 | x | add tree with locally deleted blob (SAFE+MISSING) |
|
|
| 22* | B1 | T1 | B1 | add tree AND deleted blob (SAFE) |
|
|
| 23* | B1 | T1 | B2 | add tree with delete of modified blob (F-1) |
|
|
| 24 | B1 | T1 | T1 | add tree with deleted blob (F-1) |
|
|
| 25 | T1 | x | x | independently deleted tree (SAFE+MISSING) |
|
|
| 26 | T1 | x | B1/Bi | independently deleted tree AND untrack/ign blob (F-1) |
|
|
| 27- | T1 | x | T1 | deleted tree (MAYBE SAFE) |
|
|
| 28+ | T1 | B1 | x | deleted tree AND added blob (SAFE+MISSING) |
|
|
| 29 | T1 | B1 | B1 | independently typechanged tree -> blob (F-1) |
|
|
| 30+ | T1 | B1 | B2 | typechange tree->blob with conflicting blob (F-1) |
|
|
| 31* | T1 | B1 | T1/T2 | typechange tree->blob (MAYBE SAFE) |
|
|
| 32+ | T1 | T1 | x | restore locally deleted tree (SAFE+MISSING) |
|
|
| 33 | T1 | T1 | B1/Bi | locally typechange tree->untrack/ign blob (DIRTY) |
|
|
| 34 | T1 | T1 | T1/T2 | unmodified tree (MAYBE SAFE) |
|
|
| 35+ | T1 | T2 | x | update locally deleted tree (SAFE+MISSING) |
|
|
| 36* | T1 | T2 | B1/Bi | update to tree with typechanged tree->blob conflict (F-1) |
|
|
| 37 | T1 | T2 | T1/T2/T3 | update to existing tree (MAYBE SAFE) |
|
|
|
|
|
|
The number is followed by ' ' if no change is needed or '+' if the case
|
|
needs to write to disk or '-' if something must be deleted and '*' if
|
|
there should be a delete followed by an write.
|
|
|
|
There are four tiers of safe cases:
|
|
|
|
* SAFE == completely safe to update
|
|
* SAFE+MISSING == safe except the workdir is missing the expect content
|
|
* MAYBE SAFE == safe if workdir tree matches (or is missing) baseline
|
|
content, which is unknown at this point
|
|
* FORCEABLE == conflict unless FORCE is given
|
|
* DIRTY == no conflict but change is not applied unless FORCE
|
|
|
|
Some slightly unusual circumstances:
|
|
|
|
* 8 - parent dir is only deleted when file is, so parent will be left if
|
|
empty even though it would be deleted if the file were present
|
|
* 11 - core git does not consider this a conflict but attempts to delete T1
|
|
and gives "unable to unlink file" error yet does not skip the rest
|
|
of the operation
|
|
* 12 - without FORCE file is left deleted (i.e. not restored) so new wd is
|
|
dirty (and warning message "D file" is printed), with FORCE, file is
|
|
restored.
|
|
* 24 - This should be considered MAYBE SAFE since effectively it is 7 and 8
|
|
combined, but core git considers this a conflict unless forced.
|
|
* 26 - This combines two cases (1 & 25) (and also implied 8 for tree content)
|
|
which are ok on their own, but core git treat this as a conflict.
|
|
If not forced, this is a conflict. If forced, this actually doesn't
|
|
have to write anything and leaves the new blob as an untracked file.
|
|
* 32 - This is the only case where the baseline and target values match
|
|
and yet we will still write to the working directory. In all other
|
|
cases, if baseline == target, we don't touch the workdir (it is
|
|
either already right or is "dirty"). However, since this case also
|
|
implies that a ?/B1/x case will exist as well, it can be skipped.
|
|
|
|
Cases 3, 17, 24, 26, and 29 are all considered conflicts even though
|
|
none of them will require making any updates to the working directory.
|
|
|