{"thread":{"id":"57744","subject":"suggestion for git glossary: \"ort\"","startedAt":"2022-04-16T15:15:51Z","lastAt":"2022-04-18T17:43:33Z","messageCount":4,"participants":["Steve Summit","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"453778","messageId":"2022Apr16.1107.scs.0007@quinine2.home","threadId":"57744","inReplyTo":null,"subject":"suggestion for git glossary: \"ort\"","fromName":"Steve Summit","fromEmail":"scs@eskimo.com","sentAt":"2022-04-16T15:07:09Z","receivedAt":"2022-04-16T15:15:51Z","isPatch":false,"sender":{"key":"scs@eskimo.com","avatar":null},"body":"I kept seeing references to \"ort\" in the git source code, and I\nhad no idea what it meant.  Grepping around in the Documentation\ntree eventually revealed: it's a new merge strategy!  Suggested\nglossary patch attached; feel free to improve.\n\n\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex aa2f41f..cb0726f 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -287,6 +287,13 @@ This commit is referred to as a \"merge commit\", or sometimes just a\n \torigin/name-of-upstream-branch, which you can see using\n \t`git branch -r`.\n \n+[[def_ort]]ort::\n+\tThe default merge strategy when pulling or merging one branch.\n+\tAn acronym for \"Ostensibly Recursive's Twin\", due to the fact\n+\tthat it was written as a replacement for the previous default\n+\talgorithm, `recursive`.  See linkgit:git-merge[1], section\n+\t\"Merge Strategies\".\n+\n [[def_overlay]]overlay::\n \tOnly update and add files to the working directory, but don't\n \tdelete them, similar to how 'cp -R' would update the contents\n"},{"id":"453780","messageId":"xmqq5yn84pm2.fsf@gitster.g","threadId":"57744","inReplyTo":"2022Apr16.1107.scs.0007@quinine2.home","subject":"Re: suggestion for git glossary: \"ort\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-04-16T22:42:29Z","receivedAt":"2022-04-16T22:42:34Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"scs@eskimo.com (Steve Summit) writes:\n\n> I kept seeing references to \"ort\" in the git source code, and I\n> had no idea what it meant.  Grepping around in the Documentation\n> tree eventually revealed: it's a new merge strategy!  Suggested\n> glossary patch attached; feel free to improve.\n\nIf the aim is to unconfuse those who are new to the codebase, read\nbuiltin/merge.c and merge-ort-*.[ch], and wonder what \"ort\" refers\nto, I doubt it would help all that much to add a new entry to the\nglossary, especially if they do not think of first taking a look at\n\"git merge --help\", which has its own large section on \"ort\".\n\nOr is your main issue is even after you discover that \"ort\" is one\nof the merge strategies supported by Git, it is unclear how that\nshort non-word was invented?\n\n"},{"id":"453803","messageId":"2022Apr18.0616.scs.0001@quinine2.home","threadId":"57744","inReplyTo":"xmqq5yn84pm2.fsf@gitster.g","subject":"Re: suggestion for git glossary: \"ort\"","fromName":"Steve Summit","fromEmail":"scs@eskimo.com","sentAt":"2022-04-18T10:16:25Z","receivedAt":"2022-04-18T10:20:09Z","isPatch":false,"sender":{"key":"scs@eskimo.com","avatar":null},"body":"gitster wrote:\n> scs@eskimo.com (Steve Summit) writes:\n>> I kept seeing references to \"ort\" in the git source code, and I\n>> had no idea what it meant.\n>\n> If the aim is to unconfuse those who are new to the codebase, read\n> builtin/merge.c and merge-ort-*.[ch], and wonder what \"ort\" refers\n> to, I doubt it would help all that much...\n\nAll I can say is that I am someone who is new to the codebase,\nkept seeing references to \"ort\", and had no idea what it meant.\nIt didn't occur to me that it might be a merge strategy; for all\nI knew orts were things that needed to be merged.\n\n> Or is your main issue is even after you discover that \"ort\" is one\n> of the merge strategies supported by Git, it is unclear how that\n> short non-word was invented?\n\nWell, that too, but really, my thinking was much more simple than\nthat: A glossary is where you define special terminology.  \"ort\"\nis special terminology in git.  Therefore, I thought it belonged\nin git's glossary.  BICBW.\n\n> ...I doubt it would help all that much to add a new entry to the\n> glossary, especially if they do not think of first taking a look at\n> \"git merge --help\", which has its own large section on \"ort\".\n\nCall me stupid :-), but I did not think first of looking there!\nBut you'll notice I added a link to that page in the suggested\nglossary entry.  (I doubt I got the markdown link syntax right,\nthough.)\n"},{"id":"453897","messageId":"xmqqlew2xp6r.fsf@gitster.g","threadId":"57744","inReplyTo":"2022Apr18.0616.scs.0001@quinine2.home","subject":"Re: suggestion for git glossary: \"ort\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-04-18T17:43:24Z","receivedAt":"2022-04-18T17:43:33Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"scs@eskimo.com (Steve Summit) writes:\n\n>> ...I doubt it would help all that much to add a new entry to the\n>> glossary, especially if they do not think of first taking a look at\n>> \"git merge --help\", which has its own large section on \"ort\".\n>\n> Call me stupid :-),\n\nI see a smiley, but FWIW I didn't (and I wouldn't).\n\nWhat I meant is that the most effective place to give additional\ninformation may not be another end-user facing documentation page\n(i.e. git help glossary) when a newcomer is puzzled about a word in\nthe source and another end-user facing documentation page already\nexplains the word.  After all, not all the words we see in the\ndocumentation sources are necessarily end-user facing.\n\nThe implication is that we need to look elsewhere to find a more\neffective place, if glossary isn't the place.\n\nIf we use \"ort\" (or \"recursive\" for that matter) in our sources in a\ncontext where it is not obvious that we refer to one of our merge\nstrategies, we can be a bit more helpful by saying \"ort strategy\" or\n\"recursive strategy\".  There shouldn't be too many places that refer\nto these words outside the files that _are_ about these strategies\nwhere they should not need repeated explanations (for example, the\nbig comment that starts merge-ort.c file should suffice for mentions\nof \"ort\" in four merge-ort* files).\n\n    $ git grep -l -E -e '(^|[^a-z])ort([^a-z])' -i \\*.[ch]\n    builtin/merge.c\n    builtin/rebase.c\n    log-tree.c\n    merge-ort-wrappers.c\n    merge-ort-wrappers.h\n    merge-ort.c\n    merge-ort.h\n    merge-recursive.c\n    sequencer.c\n    t/helper/test-fast-rebase.c\n\n\nOn the other hand, if the source to a \"mergy\" subcommand whose name\nis NOT \"merge\" refers to \"ort\" out of context, and it is not clear\nthat the word refers to one of the merge strategies, the reader\ndefinitely deserves help.  It is understandable that without\nfamiliarity of the architecture of Git, it would not be obvious that\nmergy operations like cherry-pick, revert and rebase heavily depend\non the merge strategy backends.  We should update the mention of\n\"ort\" in these source files to make it more clear that it is one of\nthe \"merge strategies\", at which point \"git merge --help\" would be\nan obvious next step, because that is where the strategies are\nlisted and explained.\n\nThe mention of \"ort\" in builtin/rebase.c looks like this:\n\n\t\tif (!options.strategy)\n\t\t\toptions.strategy = \"ort\";\n\nThe name of the member getting assigned to, .strategy, makes it\nalready clear that this refers to rebase_options.strategy so perhaps\n\n\t/* choice of merge strategy, e.g. \"ort\" */\n\tchar *strategy, *strategy_opts;\n\nin the definition of the rebase_options structure might help.\n\nThe only reference in merge-recursive.c is\n\n\t/* Not supported; option specific to merge-ort */\n\nwhich would be enough for readers to notice merge-ort.c is next door,\nwhich has this at the top,\n\n        /*\n         * \"Ostensibly Recursive's Twin\" merge strategy, or \"ort\" for short.  Meant\n         * as a drop-in replacement for the \"recursive\" merge strategy, allowing one\n         * to replace ...\n\nso I do not think there is anything to add there.\n\nSome mentions in sequencer.c can probably use improvements.\n"}]}