| 1 | git-pull(1) |
| 2 | =========== |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | git-pull - Fetch from and integrate with another repository or a local branch |
| 7 | |
| 8 | |
| 9 | SYNOPSIS |
| 10 | -------- |
| 11 | [synopsis] |
| 12 | git pull [<options>] [<repository> [<refspec>...]] |
| 13 | |
| 14 | |
| 15 | DESCRIPTION |
| 16 | ----------- |
| 17 | |
| 18 | Integrate changes from a remote repository into the current branch. |
| 19 | |
| 20 | First, `git pull` runs `git fetch` with the same arguments |
| 21 | (excluding merge options) to fetch remote branch(es). |
| 22 | Then it decides which remote branch to integrate: if you run `git pull` |
| 23 | with no arguments this defaults to the <<UPSTREAM-BRANCHES,upstream>> |
| 24 | for the current branch. |
| 25 | Then it integrates that branch into the current branch. |
| 26 | |
| 27 | There are 4 main options for integrating the remote branch: |
| 28 | |
| 29 | 1. `git pull --ff-only` will only do "fast-forward" updates: it |
| 30 | fails if your local branch has diverged from the remote branch. |
| 31 | This is the default. |
| 32 | 2. `git pull --rebase` runs `git rebase` |
| 33 | 3. `git pull --no-rebase` runs `git merge`. |
| 34 | 4. `git pull --squash` runs `git merge --squash` |
| 35 | |
| 36 | You can also set the configuration options `pull.rebase`, `pull.squash`, |
| 37 | or `pull.ff` with your preferred behaviour. |
| 38 | |
| 39 | If there's a merge conflict during the merge or rebase that you don't |
| 40 | want to handle, you can safely abort it with `git merge --abort` or |
| 41 | `git rebase --abort`. |
| 42 | |
| 43 | OPTIONS |
| 44 | ------- |
| 45 | |
| 46 | _<repository>_:: |
| 47 | The "remote" repository to pull from. This can be either |
| 48 | a URL (see the section <<URLS,GIT URLS>> below) or the name |
| 49 | of a remote (see the section <<REMOTES,REMOTES>> below). |
| 50 | + |
| 51 | Defaults to the configured upstream for the current branch, or `origin`. |
| 52 | See <<UPSTREAM-BRANCHES,UPSTREAM BRANCHES>> below for more on how to |
| 53 | configure upstreams. |
| 54 | |
| 55 | _<refspec>_:: |
| 56 | Which branch or other reference(s) to fetch and integrate into the |
| 57 | current branch, for example `main` in `git pull origin main`. |
| 58 | Defaults to the configured upstream for the current branch. |
| 59 | + |
| 60 | This can be a branch, tag, or other collection of reference(s). |
| 61 | See <<fetch-refspec,_<refspec>_>> below under "Options related to fetching" |
| 62 | for the full syntax, and <<DEFAULT-BEHAVIOUR,DEFAULT BEHAVIOUR>> below |
| 63 | for how `git pull` uses this argument to determine which remote branch |
| 64 | to integrate. |
| 65 | |
| 66 | `-q`:: |
| 67 | `--quiet`:: |
| 68 | This is passed to both underlying git-fetch to squelch reporting of |
| 69 | during transfer, and underlying git-merge to squelch output during |
| 70 | merging. |
| 71 | |
| 72 | `-v`:: |
| 73 | `--verbose`:: |
| 74 | Pass `--verbose` to git-fetch and git-merge. |
| 75 | |
| 76 | `--recurse-submodules[=(yes|on-demand|no)]`:: |
| 77 | `--no-recurse-submodules`:: |
| 78 | This option controls if new commits of populated submodules should |
| 79 | be fetched, and if the working trees of active submodules should be |
| 80 | updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and |
| 81 | linkgit:gitmodules[5]). |
| 82 | + |
| 83 | If the checkout is done via rebase, local submodule commits are rebased as well. |
| 84 | + |
| 85 | If the update is done via merge, the submodule conflicts are resolved and checked out. |
| 86 | |
| 87 | Options related to merging |
| 88 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 89 | |
| 90 | :git-pull: 1 |
| 91 | |
| 92 | include::merge-options.adoc[] |
| 93 | |
| 94 | `-r`:: |
| 95 | `--rebase[=(true|merges|false|interactive)]`:: |
| 96 | `true`;; rebase the current branch on top of the upstream |
| 97 | branch after fetching. If there is a remote-tracking branch |
| 98 | corresponding to the upstream branch and the upstream branch |
| 99 | was rebased since last fetched, the rebase uses that information |
| 100 | to avoid rebasing non-local changes. This is the default. |
| 101 | |
| 102 | `merges`;; rebase using `git rebase --rebase-merges` so that |
| 103 | the local merge commits are included in the rebase (see |
| 104 | linkgit:git-rebase[1] for details). |
| 105 | `false`;; merge the upstream branch into the current branch. |
| 106 | `interactive`;; enable the interactive mode of rebase. |
| 107 | |
| 108 | + |
| 109 | See `pull.rebase`, `branch.<name>.rebase` and `branch.autoSetupRebase` in |
| 110 | linkgit:git-config[1] if you want to make `git pull` always use |
| 111 | `--rebase` instead of merging. |
| 112 | + |
| 113 | [NOTE] |
| 114 | This is a potentially _dangerous_ mode of operation. |
| 115 | It rewrites history, which does not bode well when you |
| 116 | published that history already. Do *not* use this option |
| 117 | unless you have read linkgit:git-rebase[1] carefully. |
| 118 | |
| 119 | `--no-rebase`:: |
| 120 | This is shorthand for `--rebase=false`. |
| 121 | |
| 122 | Options related to fetching |
| 123 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 124 | |
| 125 | include::fetch-options.adoc[] |
| 126 | |
| 127 | include::pull-fetch-param.adoc[] |
| 128 | |
| 129 | include::urls-remotes.adoc[] |
| 130 | |
| 131 | include::merge-strategies.adoc[] |
| 132 | |
| 133 | [[DEFAULT-BEHAVIOUR]] |
| 134 | DEFAULT BEHAVIOUR |
| 135 | ----------------- |
| 136 | |
| 137 | Often people use `git pull` without giving any parameter. |
| 138 | Traditionally, this has been equivalent to saying `git pull |
| 139 | origin`. However, when configuration `branch.<name>.remote` is |
| 140 | present while on branch `<name>`, that value is used instead of |
| 141 | `origin`. |
| 142 | |
| 143 | In order to determine what URL to use to fetch from, the value |
| 144 | of the configuration `remote.<origin>.url` is consulted |
| 145 | and if there is not any such variable, the value on the `URL:` line |
| 146 | in `$GIT_DIR/remotes/<origin>` is used. |
| 147 | |
| 148 | In order to determine what remote branches to fetch (and |
| 149 | optionally store in the remote-tracking branches) when the command is |
| 150 | run without any refspec parameters on the command line, values |
| 151 | of the configuration variable `remote.<origin>.fetch` are |
| 152 | consulted, and if there aren't any, `$GIT_DIR/remotes/<origin>` |
| 153 | is consulted and its `Pull:` lines are used. |
| 154 | In addition to the refspec formats described in the OPTIONS |
| 155 | section, you can have a globbing refspec that looks like this: |
| 156 | |
| 157 | ------------ |
| 158 | refs/heads/*:refs/remotes/origin/* |
| 159 | ------------ |
| 160 | |
| 161 | A globbing refspec must have a non-empty RHS (i.e. must store |
| 162 | what were fetched in remote-tracking branches), and its LHS and RHS |
| 163 | must end with `/*`. The above specifies that all remote |
| 164 | branches are tracked using remote-tracking branches in |
| 165 | `refs/remotes/origin/` hierarchy under the same name. |
| 166 | |
| 167 | The rule to determine which remote branch to merge after |
| 168 | fetching is a bit involved, in order not to break backward |
| 169 | compatibility. |
| 170 | |
| 171 | If explicit refspecs were given on the command |
| 172 | line of `git pull`, they are all merged. |
| 173 | |
| 174 | When no refspec was given on the command line, then `git pull` |
| 175 | uses the refspec from the configuration or |
| 176 | `$GIT_DIR/remotes/<origin>`. In such cases, the following |
| 177 | rules apply: |
| 178 | |
| 179 | . If `branch.<name>.merge` configuration for the current |
| 180 | branch _<name>_ exists, that is the name of the branch at the |
| 181 | remote site that is merged. |
| 182 | |
| 183 | . If the refspec is a globbing one, nothing is merged. |
| 184 | |
| 185 | . Otherwise the remote branch of the first refspec is merged. |
| 186 | |
| 187 | |
| 188 | EXAMPLES |
| 189 | -------- |
| 190 | |
| 191 | * Update the remote-tracking branches for the repository |
| 192 | you cloned from, then merge one of them into your |
| 193 | current branch: |
| 194 | + |
| 195 | ------------------------------------------------ |
| 196 | $ git pull |
| 197 | $ git pull origin |
| 198 | ------------------------------------------------ |
| 199 | + |
| 200 | Normally the branch merged in is the `HEAD` of the remote repository, |
| 201 | but the choice is determined by the `branch.<name>.remote` and |
| 202 | `branch.<name>.merge` options; see linkgit:git-config[1] for details. |
| 203 | |
| 204 | * Merge into the current branch the remote branch `next`: |
| 205 | + |
| 206 | ------------------------------------------------ |
| 207 | $ git pull origin next |
| 208 | ------------------------------------------------ |
| 209 | + |
| 210 | This leaves a copy of `next` temporarily in `FETCH_HEAD`, and |
| 211 | updates the remote-tracking branch `origin/next`. |
| 212 | The same can be done by invoking fetch and merge: |
| 213 | + |
| 214 | ------------------------------------------------ |
| 215 | $ git fetch origin |
| 216 | $ git merge origin/next |
| 217 | ------------------------------------------------ |
| 218 | |
| 219 | |
| 220 | If you tried a pull which resulted in complex conflicts and |
| 221 | would want to start over, you can recover with `git reset`. |
| 222 | |
| 223 | |
| 224 | include::transfer-data-leaks.adoc[] |
| 225 | |
| 226 | BUGS |
| 227 | ---- |
| 228 | Using `--recurse-submodules` can only fetch new commits in already checked |
| 229 | out submodules right now. When e.g. upstream added a new submodule in the |
| 230 | just fetched commits of the superproject the submodule itself cannot be |
| 231 | fetched, making it impossible to check out that submodule later without |
| 232 | having to do a fetch again. This is expected to be fixed in a future Git |
| 233 | version. |
| 234 | |
| 235 | SEE ALSO |
| 236 | -------- |
| 237 | linkgit:git-fetch[1], linkgit:git-merge[1], linkgit:git-config[1] |
| 238 | |
| 239 | GIT |
| 240 | --- |
| 241 | Part of the linkgit:git[1] suite |