Re: [PATCH 1/2] Documentation/git-merge: reword references to "remote" and "pull"

From: Junio C Hamano <gitster@pobox.com>
Date: Jan 7, 2010, 18:01 UTC
Message-ID: <7vaawp4wvz.fsf@alter.siamese.dyndns.org>
In-Reply-To: <2e53c91e536e1ff585bc7464c1b8863e6cc45c45.1262883414.git.trast@student.ethz.ch>

Thomas Rast <trast@student.ethz.ch> writes:

Show 11 quoted lines

> 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@student.ethz.ch>
> ---

Looks sensible, modulo a few "'theirs' version" that I think should simply be "their version".

Show 6 quoted lines

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

Show 12 quoted lines

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