threads / discuss / 31914

git merge man page, upstream

Subject: git merge man page, upstream

## tl;dr

7 messages between Oct 23, 2012 and Oct 25, 2012.

replies: 6people: 4as markdown or json

Angelo Borsotti· Oct 23, 2012, 07:40 UTC · lore
Hello,
the git merge man page, OPTIONS, <commit> ... states:
   "If no commit is given from the command line, and if
merge.defaultToUpstream configuration variable is set, merge the
remote tracking branches that the current branch is configured to use
as its upstream. See also the configuration section of this manual
page."

Actually, in this case git merge merges the upstream branch, not the remote tracking branch.

Proposed change:
   "If no commit is given from the command line, and if
merge.defaultToUpstream configuration variable is set, merge the
upstream branches that the current branch has currently configured.
See also the configuration section of this manual page."
-Angelo Borsotti
Matthieu Moy· Oct 23, 2012, 07:51 UTC · re: Angelo Borsotti · lore

Re: git merge man page, upstream

Angelo Borsotti <angelo.borsotti@gmail.com> writes:
Show 12 quoted lines
> Hello,
>
> the git merge man page, OPTIONS, <commit> ... states:
>
>    "If no commit is given from the command line, and if
> merge.defaultToUpstream configuration variable is set, merge the
> remote tracking branches that the current branch is configured to use
> as its upstream. See also the configuration section of this manual
> page."
>
> Actually, in this case git merge merges the upstream branch, not the
> remote tracking branch.

It merges the upstream branch, which is a remote-tracking branch (notice the - between remote and tracking, it's a branch that tracks a remote branch, not a remote branch that tracks something).

I'll send a patch to fix that.
-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/
Matthieu Moy· Oct 23, 2012, 11:35 UTC · re: Angelo Borsotti · lore

Re: git merge man page, upstream

Angelo Borsotti <angelo.borsotti@gmail.com> writes:
> Hi Matthieu,
>
> the upstream branch can also be a local branch.
In this case, it's:
[branch "branch"]
        remote = .
        merge = refs/heads/master

which can arguably be considered as a special case of remote branch whose location happens to be ".". But as said in the patch, I don't mind if someone wants to drop the remote-tracking mention on top of my patch.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/
Angelo Borsotti· Oct 23, 2012, 17:30 UTC · re: Matthieu Moy · lore

Re: git merge man page, upstream

Hi Matthiew,

man pages should be clear, and easy to read. "Remote" usually means "another repository" (git glossary), and also in natural language conveys the notion of something far away. Internally, it can be handled as a special case of url, of course. My suggestion is to be consistent with the git glossary, that defines "upstream branch" as: "The default branch that is merged into the branch in question", which is exactly what that paragraph of the git-merge man page is describing.

-Angelo
Matthieu Moy· Oct 23, 2012, 11:34 UTC · re: Matthieu Moy · lore

[PATCH] Documentation: remote tracking branch -> remote-tracking branch

This change was already done by 0e615b252f3 (Matthieu Moy, Tue Nov 2 2010, Replace "remote tracking" with "remote-tracking"), but new instances of remote tracking (without dash) were introduced in the meantime.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
Here's the patch.

I'm not opposed to dropping completely the remote-tracking part in the case of merge (i.e. "remote-tracking branches that the current branch is configured to use as its upstream" -> "upstream branch") on top of that, but if we do this, merge-config.txt should be updated too).

 Documentation/git-clone.txt    | 4 ++--
 Documentation/git-merge.txt    | 2 +-
 Documentation/git-push.txt     | 2 +-
 Documentation/merge-config.txt | 4 ++--
 4 files changed, 6 insertions(+), 6 deletions(-)
diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 6d98ef3..7fefdb0 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -196,9 +196,9 @@ objects from the source repository into a pack in the cloned repository.
 	`--no-single-branch` is given to fetch the histories near the
 	tips of all branches.
 	Further fetches into the resulting repository will only update the
-	remote tracking branch for the branch this option was used for the
+	remote-tracking branch for the branch this option was used for the
 	initial cloning.  If the HEAD at the remote did not point at any
-	branch when `--single-branch` clone was made, no remote tracking
+	branch when `--single-branch` clone was made, no remote-tracking
 	branch is created.
 
 --recursive::
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 20f9228..d34ea3c 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -99,7 +99,7 @@ commit or stash your changes before running 'git merge'.
 	more than two parents (affectionately called an Octopus merge).
 +
 If no commit is given from the command line, and if `merge.defaultToUpstream`
-configuration variable is set, merge the remote tracking branches
+configuration variable is set, merge the remote-tracking branches
 that the current branch is configured to use as its upstream.
 See also the configuration section of this manual page.
 
diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 22d2580..fe46c42 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -175,7 +175,7 @@ useful if you write an alias or script around 'git push'.
 
 --recurse-submodules=check|on-demand::
 	Make sure all submodule commits used by the revisions to be
-	pushed are available on a remote tracking branch. If 'check' is
+	pushed are available on a remote-tracking branch. If 'check' is
 	used git will verify that all submodule commits that changed in
 	the revisions to be pushed are available on at least one remote
 	of the submodule. If any commits are missing the push will be
diff --git a/Documentation/merge-config.txt b/Documentation/merge-config.txt
index 861bd6f..9bb4956 100644
--- a/Documentation/merge-config.txt
+++ b/Documentation/merge-config.txt
@@ -9,11 +9,11 @@ merge.conflictstyle::
 merge.defaultToUpstream::
 	If merge is called without any commit argument, merge the upstream
 	branches configured for the current branch by using their last
-	observed values stored in their remote tracking branches.
+	observed values stored in their remote-tracking branches.
 	The values of the `branch.<current branch>.merge` that name the
 	branches at the remote named by `branch.<current branch>.remote`
 	are consulted, and then they are mapped via `remote.<remote>.fetch`
-	to their corresponding remote tracking branches, and the tips of
+	to their corresponding remote-tracking branches, and the tips of
 	these tracking branches are merged.
 
 merge.ff::
-- 
1.7.12.410.g5f38766
Jeff King· Oct 25, 2012, 09:54 UTC · re: Matthieu Moy · lore

Re: [PATCH] Documentation: remote tracking branch -> remote-tracking branch

On Tue, Oct 23, 2012 at 01:34:05PM +0200, Matthieu Moy wrote:
> This change was already done by 0e615b252f3 (Matthieu Moy, Tue Nov 2
> 2010, Replace "remote tracking" with "remote-tracking"), but new
> instances of remote tracking (without dash) were introduced in the
> meantime.
Thanks. It seems like an obvious step forward.
> I'm not opposed to dropping completely the remote-tracking part in the
> case of merge (i.e. "remote-tracking branches that the current branch
> is configured to use as its upstream" -> "upstream branch") on top of
> that, but if we do this, merge-config.txt should be updated too).

Yeah, I do not care too deeply, but I think it reads just fine without mentioning remote-tracking at all.

-Peff

← back to recent threads