suggestion for git glossary: "ort"

suggestion for git glossary: "ort"

[Steve Summit]

[-- Attachment #1: Type: text/plain, Size: 240 bytes --]

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.

[-- Attachment #2: glossary-content.txt.patch --]
[-- Type: text/plain, Size: 833 bytes --]

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

Re: suggestion for git glossary: "ort"

[Junio C Hamano]

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?

Re: suggestion for git glossary: "ort"

[Steve Summit]

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.)

Re: suggestion for git glossary: "ort"

[Junio C Hamano]

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.