| Message ID | 2022Apr16.1107.scs.0007@quinine2.home (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | suggestion for git glossary: "ort" | expand |
scs@eskimo.com (Steve Summit) writes: > I kept seeing references to "ort" in the git source code, and I > had no idea what it meant. Grepping around in the Documentation > tree eventually revealed: it's a new merge strategy! Suggested > glossary patch attached; feel free to improve. If the aim is to unconfuse those who are new to the codebase, read builtin/merge.c and merge-ort-*.[ch], and wonder what "ort" refers to, I doubt it would help all that much to add a new entry to the glossary, especially if they do not think of first taking a look at "git merge --help", which has its own large section on "ort". Or is your main issue is even after you discover that "ort" is one of the merge strategies supported by Git, it is unclear how that short non-word was invented?
gitster wrote: > scs@eskimo.com (Steve Summit) writes: >> I kept seeing references to "ort" in the git source code, and I >> had no idea what it meant. > > If the aim is to unconfuse those who are new to the codebase, read > builtin/merge.c and merge-ort-*.[ch], and wonder what "ort" refers > to, I doubt it would help all that much... All I can say is that I am someone who is new to the codebase, kept seeing references to "ort", and had no idea what it meant. It didn't occur to me that it might be a merge strategy; for all I knew orts were things that needed to be merged. > Or is your main issue is even after you discover that "ort" is one > of the merge strategies supported by Git, it is unclear how that > short non-word was invented? Well, that too, but really, my thinking was much more simple than that: A glossary is where you define special terminology. "ort" is special terminology in git. Therefore, I thought it belonged in git's glossary. BICBW. > ...I doubt it would help all that much to add a new entry to the > glossary, especially if they do not think of first taking a look at > "git merge --help", which has its own large section on "ort". Call me stupid :-), but I did not think first of looking there! But you'll notice I added a link to that page in the suggested glossary entry. (I doubt I got the markdown link syntax right, though.)
scs@eskimo.com (Steve Summit) writes: >> ...I doubt it would help all that much to add a new entry to the >> glossary, especially if they do not think of first taking a look at >> "git merge --help", which has its own large section on "ort". > > Call me stupid :-), I see a smiley, but FWIW I didn't (and I wouldn't). What I meant is that the most effective place to give additional information may not be another end-user facing documentation page (i.e. git help glossary) when a newcomer is puzzled about a word in the source and another end-user facing documentation page already explains the word. After all, not all the words we see in the documentation sources are necessarily end-user facing. The implication is that we need to look elsewhere to find a more effective place, if glossary isn't the place. If we use "ort" (or "recursive" for that matter) in our sources in a context where it is not obvious that we refer to one of our merge strategies, we can be a bit more helpful by saying "ort strategy" or "recursive strategy". There shouldn't be too many places that refer to these words outside the files that _are_ about these strategies where they should not need repeated explanations (for example, the big comment that starts merge-ort.c file should suffice for mentions of "ort" in four merge-ort* files). $ git grep -l -E -e '(^|[^a-z])ort([^a-z])' -i \*.[ch] builtin/merge.c builtin/rebase.c log-tree.c merge-ort-wrappers.c merge-ort-wrappers.h merge-ort.c merge-ort.h merge-recursive.c sequencer.c t/helper/test-fast-rebase.c On the other hand, if the source to a "mergy" subcommand whose name is NOT "merge" refers to "ort" out of context, and it is not clear that the word refers to one of the merge strategies, the reader definitely deserves help. It is understandable that without familiarity of the architecture of Git, it would not be obvious that mergy operations like cherry-pick, revert and rebase heavily depend on the merge strategy backends. We should update the mention of "ort" in these source files to make it more clear that it is one of the "merge strategies", at which point "git merge --help" would be an obvious next step, because that is where the strategies are listed and explained. The mention of "ort" in builtin/rebase.c looks like this: if (!options.strategy) options.strategy = "ort"; The name of the member getting assigned to, .strategy, makes it already clear that this refers to rebase_options.strategy so perhaps /* choice of merge strategy, e.g. "ort" */ char *strategy, *strategy_opts; in the definition of the rebase_options structure might help. The only reference in merge-recursive.c is /* Not supported; option specific to merge-ort */ which would be enough for readers to notice merge-ort.c is next door, which has this at the top, /* * "Ostensibly Recursive's Twin" merge strategy, or "ort" for short. Meant * as a drop-in replacement for the "recursive" merge strategy, allowing one * to replace ... so I do not think there is anything to add there. Some mentions in sequencer.c can probably use improvements.
diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index aa2f41f..cb0726f 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -287,6 +287,13 @@ This commit is referred to as a "merge commit", or sometimes just a origin/name-of-upstream-branch, which you can see using `git branch -r`. +[[def_ort]]ort:: + The default merge strategy when pulling or merging one branch. + An acronym for "Ostensibly Recursive's Twin", due to the fact + that it was written as a replacement for the previous default + algorithm, `recursive`. See linkgit:git-merge[1], section + "Merge Strategies". + [[def_overlay]]overlay:: Only update and add files to the working directory, but don't delete them, similar to how 'cp -R' would update the contents