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