Re: [PATCH 1/2] Documentation/git-merge: reword references to "remote" and "pull"
From: Junio C Hamano <hidden>
Date: 2016-06-15 22:47:59
Thomas Rast [off-list ref] writes:
The git-merge manpage was written in terms of merging a "remote", which is no longer the case: you merge local or remote-tracking branches; pull is for actual remotes. Adjust the manpage accordingly. We refer to the arguments as "commits", and change instances of "remote" to "other" (where branches are concerned) or "theirs" (where conflict sides are concerned). Remove the single reference to "pulling". Signed-off-by: Thomas Rast <redacted> ---
Looks sensible, modulo a few "'theirs' version" that I think should simply be "their version".
Out of sheer curiosity: The git-merge manpage was written in terms of merging a "remote", which is no longer the case Was this ever the case? Or is it just stale terminology?
Somewhere in between stale and lax. Originally we didn't even have refs/remotes hierarchy and the distinction between what's local and what's remote was only in the user's head, and "one branch per repository" (i.e. you do local clone to work on multiple things, and pull between them), where even a topic-branch merge is to merge a commit from a remote (= neighbouring repository of your own), was a more widely practiced workflow. Saying <commit> is much more correct than <remote> (technically it can even be a <committish>, i.e. a tag that peels to a commit). However...
quoted hunk ↗ jump to hunk
@@ -33,10 +33,10 @@ include::merge-options.txt[] used to give a good default for automated 'git merge' invocations. -<remote>...:: - Other branch heads to merge into our branch. You need at - least one <remote>. Specifying more than one <remote> - obviously means you are trying an Octopus. +<commit>...:: + Commits, usually other branch heads, to merge into our branch. + You need at least one <commit>. Specifying more than one + <commit> obviously means you are trying an Octopus.
I am tempted to suggest describing the command in terms of more common use
pattern, describing the flexible and more general form as "an aside" for
more advanced users, perhaps like this.
<branch>...:
Other branch to merge into the current branch...trying an
Octopus merge.
+
Strictly speaking, these can name arbitrary commits, not necessarily
at the tip of branches. e.g. "git merge topic{tilde}4" lets you merge
the topic except for the last 4 commits.
I don't know if such an arrangement really makes the document more
approachable to new people, or it is making the description longer and
more complicated without helping new people, though (that is why this is
just "I am tempted to").