mirror of
https://github.com/git/git.git
synced 2025-12-12 20:36:24 +01:00
428d7a0d89
From user feedback: one user mentioned that they don't know what the
term "upstream branch" means. As far as I can tell, the most complete
description is under the `--track` option in `git branch`. Upstreams
are an important concept in Git and the `git branch` man page is not an
obvious place for that information to live.
There's also a very terse description of "upstream branch" in the
glossary that's missing a lot of key information, like the fact that the
upstream is used by `git status` and `git pull`, as well as a
description in `git-config` in `branch.<name>.remote` which doesn't
explain the relationship to `git status` either.
Since the `git pull`, `git push`, and `git fetch` man pages already
include sections on REMOTES and the syntax for URLs, add a section on
UPSTREAM BRANCHES to `urls-remotes.adoc`.
In the new UPSTREAM BRANCHES section, cover the various ways that
upstreams branches are automatically set in Git, since users may
mistakenly think that their branch does not have an upstream branch if
they didn't explicitly set one.
A terminology note: Git uses two terms for this concept:
- "tracking" as in "the tracking information for the 'foo' branch"
or the `--track` option to `git branch`
- "upstream" or "upstream branch", as in `git push --set-upstream`.
This term is also used in the `git rebase` man page to refer to the
first argument to `git rebase`, as well as in `git pull` to refer to
the branch which is going to be merged into the current branch ("merge
the upstream branch into the current branch")
Use "upstream branch" as a heading for this concept even though the term
"upstream branch" is not always used strictly in the sense of "the
tracking information for the current branch". "Upstream" is used much
more often than "tracking" in the Git docs to refer to this concept and
the goal is to help users understand the docs.
Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
139 lines
4.3 KiB
Plaintext
139 lines
4.3 KiB
Plaintext
include::urls.adoc[]
|
|
|
|
REMOTES[[REMOTES]]
|
|
------------------
|
|
|
|
The name of one of the following can be used instead
|
|
of a URL as `<repository>` argument:
|
|
|
|
* a remote in the Git configuration file: `$GIT_DIR/config`,
|
|
* a file in the `$GIT_DIR/remotes` directory, or
|
|
* a file in the `$GIT_DIR/branches` directory.
|
|
|
|
All of these also allow you to omit the refspec from the command line
|
|
because they each contain a refspec which git will use by default.
|
|
|
|
Named remote in configuration file
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
You can choose to provide the name of a remote which you had previously
|
|
configured using linkgit:git-remote[1], linkgit:git-config[1]
|
|
or even by a manual edit to the `$GIT_DIR/config` file. The URL of
|
|
this remote will be used to access the repository. The refspec
|
|
of this remote will be used by default when you do
|
|
not provide a refspec on the command line. The entry in the
|
|
config file would appear like this:
|
|
|
|
------------
|
|
[remote "<name>"]
|
|
url = <URL>
|
|
pushurl = <pushurl>
|
|
push = <refspec>
|
|
fetch = <refspec>
|
|
------------
|
|
|
|
The `<pushurl>` is used for pushes only. It is optional and defaults
|
|
to `<URL>`. Pushing to a remote affects all defined pushurls or all
|
|
defined urls if no pushurls are defined. Fetch, however, will only
|
|
fetch from the first defined url if multiple urls are defined.
|
|
|
|
Named file in `$GIT_DIR/remotes`
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
You can choose to provide the name of a
|
|
file in `$GIT_DIR/remotes`. The URL
|
|
in this file will be used to access the repository. The refspec
|
|
in this file will be used as default when you do not
|
|
provide a refspec on the command line. This file should have the
|
|
following format:
|
|
|
|
------------
|
|
URL: one of the above URL formats
|
|
Push: <refspec>
|
|
Pull: <refspec>
|
|
|
|
------------
|
|
|
|
`Push:` lines are used by 'git push' and
|
|
`Pull:` lines are used by 'git pull' and 'git fetch'.
|
|
Multiple `Push:` and `Pull:` lines may
|
|
be specified for additional branch mappings.
|
|
|
|
Named file in `$GIT_DIR/branches`
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
You can choose to provide the name of a
|
|
file in `$GIT_DIR/branches`.
|
|
The URL in this file will be used to access the repository.
|
|
This file should have the following format:
|
|
|
|
|
|
------------
|
|
<URL>#<head>
|
|
------------
|
|
|
|
`<URL>` is required; `#<head>` is optional.
|
|
|
|
Depending on the operation, git will use one of the following
|
|
refspecs, if you don't provide one on the command line.
|
|
`<branch>` is the name of this file in `$GIT_DIR/branches` and
|
|
`<head>` defaults to `master`.
|
|
|
|
git fetch uses:
|
|
|
|
------------
|
|
refs/heads/<head>:refs/heads/<branch>
|
|
------------
|
|
|
|
git push uses:
|
|
|
|
------------
|
|
HEAD:refs/heads/<head>
|
|
------------
|
|
|
|
|
|
[[UPSTREAM-BRANCHES]]
|
|
UPSTREAM BRANCHES
|
|
-----------------
|
|
|
|
Branches in Git can optionally have an upstream remote branch.
|
|
Git defaults to using the upstream branch for remote operations, for example:
|
|
|
|
* It's the default for `git pull` or `git fetch` with no arguments.
|
|
* It's the default for `git push` with no arguments, with some exceptions.
|
|
For example, you can use the `branch.<name>.pushRemote` option to push
|
|
to a different remote than you pull from, and by default with
|
|
`push.default=simple` the upstream branch you configure must have
|
|
the same name.
|
|
* Various commands, including `git checkout` and `git status`, will
|
|
show you how many commits have been added to your current branch and
|
|
the upstream since you forked from it, for example "Your branch and
|
|
'origin/main' have diverged, and have 2 and 3 different commits each
|
|
respectively".
|
|
|
|
The upstream is stored in `.git/config`, in the "remote" and "merge"
|
|
fields. For example, if `main`'s upstream is `origin/main`:
|
|
|
|
------------
|
|
[branch "main"]
|
|
remote = origin
|
|
merge = refs/heads/main
|
|
------------
|
|
|
|
You can set an upstream branch explicitly with
|
|
`git push --set-upstream <remote> <branch>`
|
|
but Git will often automatically set the upstream for you, for example:
|
|
|
|
* When you clone a repository, Git will automatically set the upstream
|
|
for the default branch.
|
|
* If you have the `push.autoSetupRemote` configuration option set,
|
|
`git push` will automatically set the upstream the first time you push
|
|
a branch.
|
|
* Checking out a remote-tracking branch with `git checkout <branch>`
|
|
will automatically create a local branch with that name and set
|
|
the upstream to the remote branch.
|
|
|
|
[NOTE]
|
|
Upstream branches are sometimes referred to as "tracking information",
|
|
as in "set the branch's tracking information".
|