| 1 | Directory rename detection |
| 2 | ========================== |
| 3 | |
| 4 | Rename detection logic in diffcore-rename that checks for renames of |
| 5 | individual files is also aggregated there and then analyzed in either |
| 6 | merge-ort or merge-recursive for cases where combinations of renames |
| 7 | indicate that a full directory has been renamed. |
| 8 | |
| 9 | Scope of abilities |
| 10 | ------------------ |
| 11 | |
| 12 | It is perhaps easiest to start with an example: |
| 13 | |
| 14 | * When all of x/a, x/b and x/c have moved to z/a, z/b and z/c, it is |
| 15 | likely that x/d added in the meantime would also want to move to z/d by |
| 16 | taking the hint that the entire directory 'x' moved to 'z'. |
| 17 | |
| 18 | More interesting possibilities exist, though, such as: |
| 19 | |
| 20 | * one side of history renames x -> z, and the other renames some file to |
| 21 | x/e, causing the need for the merge to do a transitive rename so that |
| 22 | the rename ends up at z/e. |
| 23 | |
| 24 | * one side of history renames x -> z, but also renames all files within x. |
| 25 | For example, x/a -> z/alpha, x/b -> z/bravo, etc. |
| 26 | |
| 27 | * both 'x' and 'y' being merged into a single directory 'z', with a |
| 28 | directory rename being detected for both x->z and y->z. |
| 29 | |
| 30 | * not all files in a directory being renamed to the same location; |
| 31 | i.e. perhaps most the files in 'x' are now found under 'z', but a few |
| 32 | are found under 'w'. |
| 33 | |
| 34 | * a directory being renamed, which also contained a subdirectory that was |
| 35 | renamed to some entirely different location. (And perhaps the inner |
| 36 | directory itself contained inner directories that were renamed to yet |
| 37 | other locations). |
| 38 | |
| 39 | * combinations of the above; see t/t6423-merge-rename-directories.sh for |
| 40 | various interesting cases. |
| 41 | |
| 42 | Limitations -- applicability of directory renames |
| 43 | ------------------------------------------------- |
| 44 | |
| 45 | In order to prevent edge and corner cases resulting in either conflicts |
| 46 | that cannot be represented in the index or which might be too complex for |
| 47 | users to try to understand and resolve, a couple basic rules limit when |
| 48 | directory rename detection applies: |
| 49 | |
| 50 | 1) If a given directory still exists on both sides of a merge, we do |
| 51 | not consider it to have been renamed. |
| 52 | |
| 53 | 2) If a subset of to-be-renamed files have a file or directory in the |
| 54 | way (or would be in the way of each other), "turn off" the directory |
| 55 | rename for those specific sub-paths and report the conflict to the |
| 56 | user. |
| 57 | |
| 58 | 3) If the other side of history did a directory rename to a path that |
| 59 | your side of history renamed away, then ignore that particular |
| 60 | rename from the other side of history for any implicit directory |
| 61 | renames (but warn the user). |
| 62 | |
| 63 | Limitations -- detailed rules and testcases |
| 64 | ------------------------------------------- |
| 65 | |
| 66 | t/t6423-merge-rename-directories.sh contains extensive tests and commentary |
| 67 | which generate and explore the rules listed above. It also lists a few |
| 68 | additional rules: |
| 69 | |
| 70 | a) If renames split a directory into two or more others, the directory |
| 71 | with the most renames, "wins". |
| 72 | |
| 73 | b) Only apply implicit directory renames to directories if the other side |
| 74 | of history is the one doing the renaming. |
| 75 | |
| 76 | c) Do not perform directory rename detection for directories which had no |
| 77 | new paths added to them. |
| 78 | |
| 79 | Limitations -- support in different commands |
| 80 | -------------------------------------------- |
| 81 | |
| 82 | Directory rename detection is supported by 'merge' and 'cherry-pick'. |
| 83 | Other git commands which users might be surprised to see limited or no |
| 84 | directory rename detection support in: |
| 85 | |
| 86 | * diff |
| 87 | |
| 88 | Folks have requested in the past that `git diff` detect directory |
| 89 | renames and somehow simplify its output. It is not clear whether this |
| 90 | would be desirable or how the output should be simplified, so this was |
| 91 | simply not implemented. Also, while diffcore-rename has most of the |
| 92 | logic for detecting directory renames, some of the logic is still found |
| 93 | within merge-ort and merge-recursive. Fully supporting directory |
| 94 | rename detection in diffs would require copying or moving the remaining |
| 95 | bits of logic to the diff machinery. |
| 96 | |
| 97 | * am |
| 98 | |
| 99 | git-am tries to avoid a full three way merge, instead calling |
| 100 | git-apply. That prevents us from detecting renames at all, which may |
| 101 | defeat the directory rename detection. There is a fallback, though; if |
| 102 | the initial git-apply fails and the user has specified the -3 option, |
| 103 | git-am will fall back to a three way merge. However, git-am lacks the |
| 104 | necessary information to do a "real" three way merge. Instead, it has |
| 105 | to use build_fake_ancestor() to get a merge base that is missing files |
| 106 | whose rename may have been important to detect for directory rename |
| 107 | detection to function. |
| 108 | |
| 109 | * rebase |
| 110 | |
| 111 | Since am-based rebases work by first generating a bunch of patches |
| 112 | (which no longer record what the original commits were and thus don't |
| 113 | have the necessary info from which we can find a real merge-base), and |
| 114 | then calling git-am, this implies that am-based rebases will not always |
| 115 | successfully detect directory renames either (see the 'am' section |
| 116 | above). merged-based rebases (rebase -m) and cherry-pick-based rebases |
| 117 | (rebase -i) are not affected by this shortcoming, and fully support |
| 118 | directory rename detection. |