Git set upstream on a new branch

The -u in git push -u origin main is a shorthand option for --set-upstream.

When you use git push -u origin main for the first time for a local branch, it does two things:

Pushes your local main branch to the remote repository named origin. If a main branch doesn't exist on the remote yet, Git will create it.
Sets up a tracking connection (upstream) between your local main branch and the remote origin/main branch. This means that Git now remembers that your local main branch is associated with the main branch on the origin remote.

Why is this tracking connection useful?

Once the upstream is set, you can use simpler Git commands in the future:

git push: Without specifying origin main, Git will automatically push to the tracked remote branch (origin/main in this case).
git pull: Similarly, Git will automatically pull from the tracked remote branch (origin/main).
git status: Git can tell you how your local branch is related to the tracked remote branch (e.g., "Your branch is ahead of 'origin/main' by 2 commits").

In summary, the -u option in git push -u origin main is used to establish a convenient link between your local branch and its corresponding remote branch, simplifying future push and pull operations for that branch. You typically only need to use -u the very first time you push a local branch to a remote.

Yes, your understanding is absolutely correct.

First Push of main (or any initial branch): You typically use -u (or --set-upstream) to establish the tracking connection with the remote repository. This is usually done for the main branch (or master in older repositories) when you first set up your local repository and push it to the remote.
Subsequent Branches: When you create new local branches (like features/implement_x) and push them to the remote for the first time, you do not need to use -u if you don't want to set up tracking immediately.

When you run git push origin features/implement_x for a new local branch, Git will:
1. Create a new branch named features/implement_x on the origin remote.
2. Push the commits from your local features/implement_x branch to the newly created remote branch.
However, if you want to set up tracking for this new branch as well, so that future git push and git pull commands on this local branch will automatically interact with origin/features/implement_x, then you would use -u:
```
git push -u origin features/implement_x
```

In summary:

You only need to use -u once per local branch to establish the upstream tracking relationship.
It's common to do this for the main development branch (main or master) initially.
For subsequent feature or bugfix branches, you can choose whether or not to use -u depending on whether you want that local branch to automatically track its remote counterpart. If you plan to work on that branch for a while and frequently push/pull, setting up tracking with -u is convenient. If it's a short-lived branch, you might skip it.

Your example of pushing features/implement_x without -u is perfectly valid and common practice. You're only creating the remote branch and pushing your commits to it in that case.

When you clone a repository from a remote source (like GitHub) to a new local folder or a completely new PC, Git automatically sets up the remote repository you cloned from as origin.

Specifically, for the initial branch that is checked out after cloning (usually main or master, depending on the remote repository's default), Git will automatically:

Create a local branch with the same name (e.g., main).
Set up tracking (upstream) for this local branch to the remote branch origin/main (or origin/master).

You can verify this by using the command:

git branch -vv

This command lists your local branches and provides more verbose output, including the tracking information. You should see something like:

* main   <commit_hash> [origin/main: ahead 2] Your branch is ahead of 'origin/main' by 2 commits.

* master <commit_hash> [origin/master]

The [origin/main] or [origin/master] part indicates that your local branch is tracking the corresponding remote branch on origin.

Therefore, you do not need to explicitly set the upstream for the initial branch you are working on after cloning. It's done automatically by the git clone command.

However, for any new local branches you create after cloning and want to push to the remote and set up tracking, you will need to explicitly set the upstream using the -u option during the first push of that branch:

git checkout -b features/new_feature
# Make some commits
git push -u origin features/new_feature

After this first push with -u, the local features/new_feature branch will be tracking origin/features/new_feature, and subsequent git push and git pull commands on that branch can be used without specifying the remote and branch name.

You can also check the configured remotes using:

git remote -v

This will show you the remote named origin and its associated URLs for fetching and pushing.

And to see detailed information about the origin remote, including the tracked branches, you can use:

git remote show origin

If you only do:

git push origin features/new_feature

(without the -u), Git will successfully:

Create a new branch named features/new_feature on the remote repository origin (if it doesn't exist already).
Push the commits from your local features/new_feature branch to this newly created (or existing) remote branch.

However, no upstream tracking will be set up. This means Git won't remember that your local features/new_feature branch is specifically linked to origin/features/new_feature.

Subsequently, if you just run:

git push

Git will likely refuse to push and will prompt you with an error message similar to this:

fatal: The current branch features/new_feature has no upstream branch.
To push the current branch and set the remote as upstream, use

    git push --set-upstream origin features/new_feature

To have this happen automatically for branches created here, see
`git help config` and the `push.autoSetupRemote` option.

In summary:

The first git push origin features/new_feature will succeed in pushing your branch to the remote.
Subsequent plain git push commands on that local features/new_feature branch will fail because Git doesn't know where to push to (it hasn't been told about its upstream remote branch).
Git will prompt you with the correct command to set the upstream (git push --set-upstream origin features/new_feature).

You would then need to either run the suggested command to set the upstream or explicitly specify the remote and branch every time you push from that local branch (e.g., git push origin features/new_feature).

joe-oli/git-set-upstream.md