| 1 | include::urls.adoc[] |
| 2 | |
| 3 | REMOTES[[REMOTES]] |
| 4 | ------------------ |
| 5 | |
| 6 | The name of one of the following can be used instead |
| 7 | of a URL as _<repository>_ argument: |
| 8 | |
| 9 | * a remote in the Git configuration file: `$GIT_DIR/config`, |
| 10 | * a file in the `$GIT_DIR/remotes` directory, or |
| 11 | * a file in the `$GIT_DIR/branches` directory. |
| 12 | |
| 13 | All of these also allow you to omit the refspec from the command line |
| 14 | because they each contain a refspec which git will use by default. |
| 15 | |
| 16 | Named remote in configuration file |
| 17 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 18 | |
| 19 | You can choose to provide the name of a remote which you had previously |
| 20 | configured using linkgit:git-remote[1], linkgit:git-config[1] |
| 21 | or even by a manual edit to the `$GIT_DIR/config` file. The URL of |
| 22 | this remote will be used to access the repository. The refspec |
| 23 | of this remote will be used by default when you do |
| 24 | not provide a refspec on the command line. The entry in the |
| 25 | config file would appear like this: |
| 26 | |
| 27 | ------------ |
| 28 | [remote "<name>"] |
| 29 | url = <URL> |
| 30 | pushurl = <pushurl> |
| 31 | push = <refspec> |
| 32 | fetch = <refspec> |
| 33 | ------------ |
| 34 | |
| 35 | The _<pushurl>_ is used for pushes only. It is optional and defaults |
| 36 | to _<URL>_. Pushing to a remote affects all defined pushurls or all |
| 37 | defined urls if no pushurls are defined. Fetch, however, will only |
| 38 | fetch from the first defined url if multiple urls are defined. |
| 39 | |
| 40 | Named file in `$GIT_DIR/remotes` |
| 41 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 42 | |
| 43 | You can choose to provide the name of a |
| 44 | file in `$GIT_DIR/remotes`. The URL |
| 45 | in this file will be used to access the repository. The refspec |
| 46 | in this file will be used as default when you do not |
| 47 | provide a refspec on the command line. This file should have the |
| 48 | following format: |
| 49 | |
| 50 | ------------ |
| 51 | URL: one of the above URL formats |
| 52 | Push: <refspec> |
| 53 | Pull: <refspec> |
| 54 | |
| 55 | ------------ |
| 56 | |
| 57 | `Push:` lines are used by `git push` and |
| 58 | `Pull:` lines are used by `git pull` and `git fetch`. |
| 59 | Multiple `Push:` and `Pull:` lines may |
| 60 | be specified for additional branch mappings. |
| 61 | |
| 62 | Named file in `$GIT_DIR/branches` |
| 63 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 64 | |
| 65 | You can choose to provide the name of a |
| 66 | file in `$GIT_DIR/branches`. |
| 67 | The URL in this file will be used to access the repository. |
| 68 | This file should have the following format: |
| 69 | |
| 70 | |
| 71 | ------------ |
| 72 | <URL>#<head> |
| 73 | ------------ |
| 74 | |
| 75 | _<URL>_ is required; `#<head>` is optional. |
| 76 | |
| 77 | Depending on the operation, git will use one of the following |
| 78 | refspecs, if you don't provide one on the command line. |
| 79 | _<branch>_ is the name of this file in `$GIT_DIR/branches` and |
| 80 | _<head>_ defaults to `master`. |
| 81 | |
| 82 | git fetch uses: |
| 83 | |
| 84 | ------------ |
| 85 | refs/heads/<head>:refs/heads/<branch> |
| 86 | ------------ |
| 87 | |
| 88 | git push uses: |
| 89 | |
| 90 | ------------ |
| 91 | HEAD:refs/heads/<head> |
| 92 | ------------ |
| 93 | |
| 94 | |
| 95 | [[UPSTREAM-BRANCHES]] |
| 96 | UPSTREAM BRANCHES |
| 97 | ----------------- |
| 98 | |
| 99 | Branches in Git can optionally have an upstream remote branch. |
| 100 | Git defaults to using the upstream branch for remote operations, for example: |
| 101 | |
| 102 | * It's the default for `git pull` or `git fetch` with no arguments. |
| 103 | * It's the default for `git push` with no arguments, with some exceptions. |
| 104 | For example, you can use the `branch.<name>.pushRemote` option to push |
| 105 | to a different remote than you pull from, and by default with |
| 106 | `push.default=simple` the upstream branch you configure must have |
| 107 | the same name. |
| 108 | * Various commands, including `git checkout` and `git status`, will |
| 109 | show you how many commits have been added to your current branch and |
| 110 | the upstream since you forked from it, for example "Your branch and |
| 111 | 'origin/main' have diverged, and have 2 and 3 different commits each |
| 112 | respectively". |
| 113 | |
| 114 | The upstream is stored in `.git/config`, in the "`remote`" and "`merge`" |
| 115 | fields. For example, if `main`'s upstream is `origin/main`: |
| 116 | |
| 117 | ------------ |
| 118 | [branch "main"] |
| 119 | remote = origin |
| 120 | merge = refs/heads/main |
| 121 | ------------ |
| 122 | |
| 123 | You can set an upstream branch explicitly with |
| 124 | `git push --set-upstream <remote> <branch>` |
| 125 | but Git will often automatically set the upstream for you, for example: |
| 126 | |
| 127 | * When you clone a repository, Git will automatically set the upstream |
| 128 | for the default branch. |
| 129 | * If you have the `push.autoSetupRemote` configuration option set, |
| 130 | `git push` will automatically set the upstream the first time you push |
| 131 | a branch. |
| 132 | * Checking out a remote-tracking branch with `git checkout <branch>` |
| 133 | will automatically create a local branch with that name and set |
| 134 | the upstream to the remote branch. |
| 135 | |
| 136 | [NOTE] |
| 137 | Upstream branches are sometimes referred to as "tracking information", |
| 138 | as in "set the branch's tracking information". |