What does git --set-upstream
do?
I tried to understand it by reading the git manual, but I didn't quite get it.
What does git --set-upstream
do?
I tried to understand it by reading the git manual, but I didn't quite get it.
To avoid confusion,
recent versions ofgit
deprecate this somewhat ambiguous--set-upstream
option
in favor of a more verbose--set-upstream-to
option
with identical syntax and behavior.
[ Reference ]
git branch --set-upstream-to <remote-branch>
sets the default remote branch for the current local branch.
Any future git pull
command (with the current local branch checked-out),
will attempt to bring in commits from the <remote-branch>
into the current local branch.
git push -u origin <local-branch>
This automatically creates an upstream counterpart branch for any future push/pull attempts from teh current <local-branch>
. The upstream remote branch derived from the branch name - <local-branch>
is also configured as the default for all subsequent actions like push/pull etc.
For example,
executing the above command for <local-branch>
= test
,
will result in creating a <remote branch>
= remotes/origin/test
.
Note: One way to avoid having to explicitly type --set-upstream
/ --set-upstream-to
is to use its shorthand flag -u
.
For more details, check out this detailed explanation about upstream branches and tracking.
git push -u origin local-branch
what does the origin
represent? Is there any case where I would type anything other than origin
after the -u
?
Commented
Mar 5, 2018 at 19:02
origin
refers to the remote git repository that was used to clone from. There can be multiple remote git repositories. In such a case, origin
may be replaced with the proper name of the desired remote that one wishes to refer to.
Commented
Mar 6, 2018 at 5:57
git remote -v
to find your remotes, the default one is origin
usually
Commented
Aug 7, 2018 at 4:00
git push -u origin local-branch
there isn't actually any remote branch listed, only a remote name and a local branch. So how does it make sense, in that second command listed, that we are setting a new default remote branch? The first example in this answer makes more sense.
git push
. Updated the answer; hopefully it is more clear now. :-)
Commented
Aug 2 at 4:41
When you push to a remote and you use the --set-upstream
flag git sets the branch you are pushing to as the remote tracking branch of the branch you are pushing.
Adding a remote tracking branch means that git then knows what you want to do when you git fetch
, git pull
or git push
in future. It assumes that you want to keep the local branch and the remote branch it is tracking in sync and does the appropriate thing to achieve this.
You could achieve the same thing with git branch --set-upstream-to
or git checkout --track
. See the git help pages on tracking branches for more information.
git branch --set-upstream <<origin/branch>>
is officially not supported anymore and is replaced by git branch --set-upstream-to <<origin/branch>>
--set-upstream
is used to map a branch in your local to a branch on remote so that you can just do git push or git pull and it will know which branch to push/pull from
For adding a remote repo I use these commands
git remote -v
git remote add upstream <URL>
git remote -v
By using the same commands above, it is possible to have multiple remotes to a local repository.
Just change the upstream name git remote add NAME <URL>
I'm assuming that your question is:
What does
git push --set-upstream <repository> <branchname>
do?
As you see, I assumed that the git command in question is git push
. I hope that is what you meant. For simplifying the answer, I further specified that the local branch <branchname> that you are on has the same name as the remote branch on your upstream repository <repository> that you are pushing to. Finally, I assume a common git configuration.
With that said, this is my answer:
In addition to the operation that a git push
without the option --set-upstream
does, this option makes git push
set at least two configuration variables:
That's all this command does. It stores upstream information (i.e., remote repository and branch) for the local branch in config variables.
Upstream information is stored under the local branch name. If your local branch is called main
, the respective config variables are branch.main.remote
and branch.main.merge
. Based on the way how this upstream information is stored, a local branch can have no more than a single set of upstream information.
You can query whether any of these config variables are set using git config --get-regexp ^branch\.
. This will output any variables that start with "branch."
The magic happens when these config variables are used by, e.g., git fetch
, git pull
or git push
to figure out the upstream repository and remote branch for a local branch if you don't explicitly specify them on the commandline. That is, when these config variables are set, you can just issue git push
and git will know (using these variables) the remote repository and upstream branch to use.
Suggested further reading:
But watch out for git quirks:
If <repository> is given as an URL or file path, see for example this example:
git push --set-upstream [email protected]:namespace/myproject.git master
git push
does not create a reference to the remote branch head in .git/refs/remotes/<repository>
Only if the upstream repository has been given a name using
git remote add <repository> <URL>
and git push --set-upstream
has been used with this name, the full power of remote tracking branches is available in all git commands.
Suggested further reading:
FYI: all commands tested with git V2.32 on Windows.
--set-upstream
is not just about git branch -u
or git push -u
.
You also have git fetch --set-upstream
and git pull --set-upstream
.
If the remote is fetched successfully, add upstream (tracking) reference, used by argument-less
git pull
and other commands
It will set:
branch.<name>.remote
branch.<name>.merge
That will allow git push
to know where to push, and to which remote branch to push to.
But: "git fetch --set-upstream
"(man) did not check if there is a current branch, leading to a segfault when it is run on a detached HEAD, which has been corrected with Git 2.35 (Q1 2022).
See commit 17baeaf (07 Dec 2021) by Ævar Arnfjörð Bjarmason (avar
).
(Merged by Junio C Hamano -- gitster
-- in commit dcaf17c, 22 Dec 2021)
pull, fetch
: fix segfault in --set-upstream optionReported-by: Clemens Fruhwirth
Reported-by: Jan Pokorný
Signed-off-by: Ævar Arnfjörð Bjarmason
Fix a segfault in the
--set-upstream
option added in 24bc1a1 (pull, 2019-08-19, Git v2.24.0-rc0 -- merge listed in batch #2) (pull, fetch:add
(man)--set-upstream
option, 2019-08-19) added in v2.24.0.The code added there did not do the same checking we do for "
git branch
"(man) itself since 8efb889 ("branch
: segfault fixes and validation", 2013-02-23, Git v1.8.3-rc0 -- merge listed in batch #2), which in turn fixed the same sort of segfault I'm fixing now in "git branch --set-upstream-to
"(man), see 6183d82 ("branch
: introduce--set-upstream-to
", 2012-08-20, Git v1.8.0-rc0 -- merge listed in batch #5).The warning message I'm adding here is an amalgamation of the error added for "
git branch
" in 8efb889, and the error outputinstall_branch_config()
itself emits, i.e.
it trims "refs/heads/
" from the name and says "branch X on remote
", not "branch refs/heads/X on remote
".
New warning:
could not set upstream of HEAD to 'X' from 'X'
when it does not point to any branch
I think it would make more sense to simply
die()
here, but in the other checks for--set-upstream
added in 24bc1a1, we issue a warning() instead.
Let's do the same here for consistency for now.There was an earlier submitted alternate way of fixing this in this thread, due to that patch breaking threading with the original report at this thread.
I didn't notice it before authoring this version.
I think the more detailed warning message here is better, and we should also have tests for this behavior.The
--no-rebase
option to "git pull
"(man) is needed as of the recently merged 7d0daf3 ("Merge branch 'en/pull-conflicting-options'", 2021-08-30, Git v2.34.0-rc0 -- merge listed in batch #2).
git push --set-upstream
.