Thomas Rast <trast@xxxxxxxxxxxxxxx> 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 <trast@xxxxxxxxxxxxxxx>
> ---
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...
> @@ -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").
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html