Name

git-pull  - 從另一個存儲庫或本地分支獲取并與其集成

概要

git pull [options] [<repository> [<refspec>…]]

描述

將遠(yuǎn)程存儲庫中的更改合并到當(dāng)前分支中。在其默認(rèn)模式下，git pull是git fetch后面的簡寫git merge FETCH_HEAD。

更確切地說，使用給定的參數(shù)git pull運行git fetch并調(diào)用git merge將檢索到的分支頭合并到當(dāng)前分支中。與--rebase，它運行，git rebase而不是git merge。

<repository> 應(yīng)該是傳遞給 git-fetch [1]的遠(yuǎn)程倉庫的名稱。 <refspec> 可以為任意的遠(yuǎn)程參考（例如，標(biāo)簽的名稱）或者甚至是具有相應(yīng)遠(yuǎn)程跟蹤分支的參考集合（例如，refs / heads / *：refs / remotes / origin / *）命名，但是通常它是遠(yuǎn)程存儲庫中分支的名稱。

從 git-branch [1]設(shè)置的當(dāng)前分支的“remote”和“merge”配置中讀取 <repository> 和 <branch> 的默認(rèn)值--track。

假設(shè)存在以下歷史記錄并且當(dāng)前分支是“ master”：

          A---B---C master on origin         /
    D---E---F---G master        ^
        origin/master in your repository

然后，“ git pull”將從遠(yuǎn)程master分支獲取并重放更改，因為它從本地master（即E）分離，直到其當(dāng)前的 commit（C），master并將結(jié)果記錄在新的提交中以及兩個父提交的名稱和來自用戶的描述更改的日志消息。

          A---B---C origin/master         /         \
    D---E---F---G---H master

有關(guān)詳細(xì)信息，請參閱 git-merge [1]，包括如何呈現(xiàn)和處理沖突。

在 Git 1.7.0 或更高版本中，要取消沖突的合并，請使用git reset --merge。警告：在較舊版本的 Git 中，git pull不鼓勵使用未提交的更改運行：盡管可能，但它會使您處于可能很難在沖突情況下退出的狀態(tài)。

如果任何遠(yuǎn)程更改與本地未提交的更改重疊，則合并將自動取消并且工作樹不受影響。通常最好在使用 git-stash [1]提取或存儲它們之前，先在工作順序中進行任何本地更改。

選項

-q   --quiet

這被傳遞給底層的 git-fetch，以便在傳輸過程中壓制報告，并在合并過程中將潛在的 git-merge 壓制成靜噪輸出。

-v   --verbose

Pass --verbose git-fetch 和 git-merge。

--no-遞歸-子模塊= YES |on-demand| 無

該選項控制是否應(yīng)該提取和更新所有已填充子模塊的新提交（請參閱 git-config [1] 和 gitmodules [5]）。

如果校驗通過 rebase 完成，則本地子模塊提交也會重新發(fā)布。

如果更新是通過合并完成的，則子模塊沖突將被解析并檢出。

與合并有關(guān)的選項

--commit   --no-commit

執(zhí)行合并然后提交結(jié)果。這個選項可以用來覆蓋 --no-commit。

使用 --no-commit 執(zhí)行合并，但假裝合并失敗并且不自動提交，以使用戶有機會在提交之前檢查并進一步調(diào)整合并結(jié)果。

--edit   -e   --no-edit

在提交成功的機械合并之前調(diào)用編輯器來進一步編輯自動生成的合并消息，以便用戶可以解釋并驗證合并。--no-edit選項可用于接受自動生成的消息（這通常是不鼓勵的）。

較舊的腳本可能取決于不允許用戶編輯合并日志消息的歷史行為。他們將在運行時看到編輯器打開git merge。為了更容易地將這些腳本調(diào)整為更新的行為，GIT_MERGE_AUTOEDIT可以將環(huán)境變量設(shè)置為no它們的開頭。

--ff

當(dāng)合并解析為快進時，只更新分支指針，而不創(chuàng)建合并提交。這是默認(rèn)行為。

--no-ff

即使合并解析為快進，也可以創(chuàng)建合并提交。這是合并注釋（可能有符號）標(biāo)記時的默認(rèn)行為。

--ff-only

拒絕合并而后以非零狀態(tài)退出，除非電流HEAD已經(jīng)是最新的或合并可以解決為快進。

--log=<n>   --no-log

除了分支名稱之外，還可以用來自至多 <n> 實際提交的單行描述來填充日志消息。另請參閱 git-fmt-merge-msg [1]。

使用 --no-log 不會列出要合并的實際提交的單行描述。

--stat   -n   --no-stat

在合并結(jié)束時顯示 diffstat。diffstat 也由配置選項 merge.stat 控制。

使用 -n 或 --no-stat 不會在合并結(jié)束時顯示 diffstat 。

--squash   --no-squash

生成工作樹和索引狀態(tài)，就像發(fā)生真正的合并（合并信息除外）一樣，但實際上并未進行提交，移動HEAD或記錄$GIT_DIR/MERGE_HEAD（以導(dǎo)致下一個git commit命令創(chuàng)建合并提交）。這允許您在當(dāng)前分支上創(chuàng)建一個單獨的提交，其效果與合并另一個分支相同（或者在章魚的情況下更多）。

用 --no-squash 執(zhí)行合并并提交結(jié)果。這個選項可以用來覆蓋 --squash。

-s <strategy>   --strategy=<strategy>

使用給定的合并策略; 可以多次提供，以按照他們應(yīng)該嘗試的順序指定它們。如果沒有-s選項，則使用內(nèi)置策略列表（否則git merge-recursive合并單個頭部時git merge-octopus）。

-X <option>   --strategy-option=<option>

將合并策略特定選項傳遞給合并策略。

--verify-signatures   --no-verify-signatures

驗證被合并的分支的提示提交是否使用有效密鑰簽名，即具有有效 uid 的密鑰：在默認(rèn)信任模型中，這意味著簽名密鑰已由可信密鑰簽名。如果側(cè)分支的提示提交未使用有效密鑰進行簽名，則會中止合并。

--summary   --no-summary

同義詞 --stat 和 --no-stat; 這些已被棄用，并將在未來被刪除。

--allow-unrelated-histories

默認(rèn)情況下，git merge命令拒絕合并不共享上代的歷史記錄。在合并兩個獨立開始他們的生活的項目的歷史時，可以使用此選項來覆蓋此安全性。由于這是非常罕見的情況，因此默認(rèn)情況下不存在配置變量，因此不會添加該變量。

-r --rebase = false | true | preserve | interactive

如果為 true，則在獲取后重新綁定上游分支頂部的當(dāng)前分支。如果存在與上游分支相對應(yīng)的遠(yuǎn)程跟蹤分支，并且上游分支自上次獲取后重新分配，則重新分配使用該信息以避免重新分配非本地更改。

設(shè)置為保留時，使用--preserve-merges傳遞給選項的 rebase，git rebase以便本地創(chuàng)建的合并提交不會變平。

如果為 false，則將當(dāng)前分支合并到上游分支中。

當(dāng)interactive ，使得交互模式重新調(diào)整。

如果你想讓git pull經(jīng)常使用 --rebase而不是合并，看pull.rebase，branch.<name>.rebase 和branch.autoSetupRebase在 git-config [1]，

--no-rebase

早先覆蓋--rebase。

--autostash   --no-autostash

在開始 rebase 之前，如果需要，將局部修改存儲（請參閱 git-stash [1]），并在完成時應(yīng)用存儲條目。--no-autostash可以覆蓋rebase.autoStash配置變量（請參閱 git-config [1]）。

該選項僅在使用“--rebase”時有效。

與 fetch 相關(guān)的選項

--all

取回所有遠(yuǎn)端。

-a   --append

追加 refs 的 ref 名稱和對象名稱到現(xiàn)有的內(nèi)容.git/FETCH_HEAD。如果沒有這個選項，舊的數(shù)據(jù).git/FETCH_HEAD將被覆蓋。

--depth=<depth>

將提取限制為從每個遠(yuǎn)程分支歷史記錄的提示中指定的提交數(shù)量。如果獲取到由git clone創(chuàng)建的 --depth=<depth> 選項（請參閱 git-clone [1]），請將歷史記錄加深或縮短為指定的提交數(shù)。深化提交的標(biāo)簽不會被提取。

--deepen=<depth>

與 --depth 相似，只是它指定了來自當(dāng)前淺層邊界而不是每個遠(yuǎn)程分支歷史記錄的提示的提交數(shù)。

--shallow-since=<date>

加深或縮短淺儲存庫的歷史記錄以在 <date> 之后包含所有可訪問的提交。

--shallow-exclude=<revision>

加深或縮短淺儲存庫的歷史記錄以排除可從指定遠(yuǎn)程分支或標(biāo)記訪問的提交。該選項可以多次指定。

--unshallow

如果源存儲庫已完成，請將淺層存儲庫轉(zhuǎn)換為完整存儲庫，以消除淺存儲庫施加的所有限制。

如果源存儲庫較淺，則盡可能多地獲取，以便當(dāng)前存儲庫具有與源存儲庫相同的歷史記錄。

--update-shallow

默認(rèn)情況下，從淺倉庫中獲取時，git fetch拒絕需要更新 .git / shallow 的引用。該選項更新 .git / shallow 并接受此類參考。

-f   --force

當(dāng)git fetch與<rbranch>:<lbranch> refspec 一起使用時，它拒絕更新本地分支<lbranch>，除非<rbranch>獲取的遠(yuǎn)程分支是后代<lbranch>。該選項將覆蓋該檢查。

-k   --keep

持續(xù)下載的包。

--no-tags

默認(rèn)情況下，指向從遠(yuǎn)程存儲庫下載的對象的標(biāo)簽將在本地獲取并存儲。該選項將禁用此自動標(biāo)記。遠(yuǎn)程的默認(rèn)行為可以通過遠(yuǎn)程。<name> .tagOpt 設(shè)置指定。請參閱 git-config [1]。

-u   --update-head-ok

默認(rèn)情況下git fetch拒絕更新對應(yīng)于當(dāng)前分支的前端。此標(biāo)志禁用檢查。這純粹是供內(nèi)部使用git pull來溝通git fetch，除非你是該項目的擁有者，否則你不應(yīng)該使用它。

--upload-pack <upload-pack>

當(dāng)給出并且從中獲取的存儲庫被處理時git fetch-pack，--exec=<upload-pack>被傳遞給該命令以指定在另一端運行的命令的非默認(rèn)路徑。

--progress

當(dāng)連接到終端時，默認(rèn)情況下，標(biāo)準(zhǔn)錯誤流中會報告進度狀態(tài)，除非指定了 -q 。即使標(biāo)準(zhǔn)錯誤流未定向到終端，此標(biāo)志也會強制進度狀態(tài)。

-4   --ipv4

僅使用 IPv4 地址，忽略 IPv6 地址。

-6   --ipv6

僅使用 IPv6 地址，忽略 IPv4 地址。

<repository>

作為提取或拉取操作源的“遠(yuǎn)程”存儲庫。此參數(shù)可以是 URL（請參閱下面的 GIT URLS 部分）或遠(yuǎn)程名稱（請參閱下面的 REMOTES 部分）。

<refspec>

指定要獲取哪些引用以及哪些本地引用要更新。當(dāng)命令行中沒有 <refspec> 時，remote.<repository>.fetch取而代之的是從變量中讀?。▍⒁?git-fetch [1]）。

一個 <refspec> 參數(shù)的格式是一個可選的 plus +，后跟 source <src>，后跟一個冒號:，后跟目標(biāo) ref <dst>。當(dāng) <dst> 為空時，可以省略冒號。<src> 通常是 ref，但它也可以是拼寫完整的十六進制對象名稱。

tag <tag>意味著與refs/tags/<tag>:refs/tags/<tag>相同; 它請求將所有內(nèi)容都提取到給定的標(biāo)簽。

匹配 <src> 的遠(yuǎn)程 ref 被取出，如果 <dst> 不是空字符串，匹配它的本地引用使用 <src> 進行快速轉(zhuǎn)發(fā)。如果使用可選的 plus +，即使不引起快速更新，本地 ref 也會被更新。

Git 網(wǎng)址

通常，URL 包含有關(guān)傳輸協(xié)議，遠(yuǎn)程服務(wù)器地址和存儲庫路徑的信息。根據(jù)傳輸協(xié)議，這些信息可能不存在。

Git 支持 ssh，git，http 和 https 協(xié)議（另外，ftp 和 ftps 可用于提取，但效率低下，不推薦使用;不要使用它）。

本地傳輸（即 git：// URL）不進行身份驗證，因此在不安全的網(wǎng)絡(luò)上應(yīng)謹(jǐn)慎使用。

以下語法可以與它們一起使用：

• ssh://user@host.xz:port/path/to/repo.git/

• git://host.xz:port/path/to/repo.git/

• https://host.xz:port/path/to/repo.git/

• ftps://host.xz:port/path/to/repo.git/

ssh 協(xié)議也可以使用另一種類似 scp 的語法：

• user@host.xz：path / to / repo.git /只有在第一個冒號前沒有斜線時才能識別此語法。這有助于區(qū)分包含冒號的本地路徑。例如，本地路徑foo:bar可以被指定為絕對路徑或./foo:bar避免被誤解為 ssh url。ssh 和 git 協(xié)議還支持?用戶名擴展：

• ssh://user@host.xz:port/~user/path/to/repo.git/

• git://host.xz:port/~user/path/to/repo.git/

• user@host.xz:/~user/path/to/repo.git/

對于本地支持的本地存儲庫，可以使用以下語法：

• /path/to/repo.git/

• file:///path/to/repo.git/

這兩種語法大多是相同的，除了克隆時，前者意味著 --local 選項。有關(guān)詳細(xì)信息，請參閱 git-clone [1]。

當(dāng) Git 不知道如何處理某個傳輸協(xié)議時，它會嘗試使用remote-<transport>遠(yuǎn)程助手（如果存在）。要顯式請求遠(yuǎn)程助手，可以使用以下語法：

• <transport>::<address>where <address> may be a path, a server and path, or an arbitrary URL-like string recognized by the specific remote helper being invoked. See gitremote-helpers[1] for details.If there are a large number of similarly-named remote repositories and you want to use a different format for them (such that the URLs you use will be rewritten into URLs that work), you can create a configuration section of the form:        [url "<actual url base>"]                insteadOf = <other url base>For example, with this:        [url "git://git.host.xz/"]                insteadOf = host.xz:/path/to/                insteadOf = work:a URL like "work:repo.git" or like "host.xz:/path/to/repo.git" will be rewritten in any context that takes a URL to be "git://git.host.xz/repo.git".If you want to rewrite URLs for push only, you can create a configuration section of the form:        [url "<actual url base>"]                pushInsteadOf = <other url base>For example, with this:        [url "ssh://example.org/"]                pushInsteadOf = git://example.org/a URL like "git://example.org/path/to/repo.git" will be rewritten to "ssh://example.org/path/to/repo.git" for pushes, but pulls will still use the original URL.RemotesThe 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 git-remote[1], 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>.

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 format
        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>

Merge strategies

The merge mechanism (git merge and git pull commands) allows the backend merge strategies to be chosen with -s option. Some strategies can also take their own options, which can be passed by giving -X<option> arguments to git merge and/or git pull.

resolve

This can only resolve two heads (i.e. the current branch and another branch you pulled from) using a 3-way merge algorithm. It tries to carefully detect criss-cross merge ambiguities and is considered generally safe and fast.

recursive

This can only resolve two heads using a 3-way merge algorithm. When there is more than one common ancestor that can be used for 3-way merge, it creates a merged tree of the common ancestors and uses that as the reference tree for the 3-way merge. This has been reported to result in fewer merge conflicts without causing mismerges by tests done on actual merge commits taken from Linux 2.6 kernel development history. Additionally this can detect and handle merges involving renames. This is the default merge strategy when pulling or merging one branch.

The recursive strategy can take the following options:

ours

This option forces conflicting hunks to be auto-resolved cleanly by favoring our version. Changes from the other tree that do not conflict with our side are reflected to the merge result. For a binary file, the entire contents are taken from our side.

This should not be confused with the ours merge strategy, which does not even look at what the other tree contains at all. It discards everything the other tree did, declaring our history contains all that happened in it.

theirs

This is the opposite of ours; note that, unlike ours, there is no theirs merge stragegy to confuse this merge option with.

patience

With this option, merge-recursive spends a little extra time to avoid mismerges that sometimes occur due to unimportant matching lines (e.g., braces from distinct functions). Use this when the branches to be merged have diverged wildly. See also git-diff[1] --patience.

diff-algorithm=patience|minimal|histogram|myers

Tells merge-recursive to use a different diff algorithm, which can help avoid mismerges that occur due to unimportant matching lines (such as braces from distinct functions). See also git-diff[1] --diff-algorithm.

ignore-space-change   ignore-all-space   ignore-space-at-eol

Treats lines with the indicated type of whitespace change as unchanged for the sake of a three-way merge. Whitespace changes mixed with other changes to a line are not ignored. See also git-diff[1] -b, -w, and --ignore-space-at-eol.

• If their version only introduces whitespace changes to a line, our version is used;

• If our version introduces whitespace changes but their version includes a substantial change, their version is used;

• Otherwise, the merge proceeds in the usual way.   renormalize   This runs a virtual check-out and check-in of all three stages of a file when resolving a three-way merge. This option is meant to be used when merging branches with different clean filters or end-of-line normalization rules. See "Merging branches with differing checkin/checkout attributes" in gitattributes[5] for details.   no-renormalize   Disables the renormalize option. This overrides the merge.renormalize configuration variable.   no-renames   Turn off rename detection. See also git-diff[1] --no-renames.   find-renames=<n>   Turn on rename detection, optionally setting the similarity threshold. This is the default. See also git-diff[1] --find-renames.   rename-threshold=<n>   Deprecated synonym for find-renames=<n>.   subtree=<path>   This option is a more advanced form of subtree strategy, where the strategy makes a guess on how two trees must be shifted to match with each other when merging. Instead, the specified path is prefixed (or stripped from the beginning) to make the shape of two trees to match.   octopus   This resolves cases with more than two heads, but refuses to do a complex merge that needs manual resolution. It is primarily meant to be used for bundling topic branch heads together. This is the default merge strategy when pulling or merging more than one branch.   ours   This resolves any number of heads, but the resulting tree of the merge is always that of the current branch head, effectively ignoring all changes from all other branches. It is meant to be used to supersede old development history of side branches. Note that this is different from the -Xours option to the recursive merge strategy.   subtree   This is a modified recursive strategy. When merging trees A and B, if B corresponds to a subtree of A, B is first adjusted to match the tree structure of A, instead of reading the trees at the same level. This adjustment is also done to the common ancestor tree.With the strategies that use 3-way merge (including the default, recursive), if a change is made on both branches, but later reverted on one of the branches, that change will be present in the merged result; some people find this behavior confusing. It occurs because only the heads and the merge base are considered when performing a merge, not the individual commits. The merge algorithm therefore considers the reverted change as no change at all, and substitutes the changed version instead.Default behaviourOften people use git pull without giving any parameter. Traditionally, this has been equivalent to saying git pull origin. However, when configuration branch.<name>.remote is present while on branch <name>, that value is used instead of origin.In order to determine what URL to use to fetch from, the value of the configuration remote.<origin>.url is consulted and if there is not any such variable, the value on the URL: line in $GIT_DIR/remotes/<origin> is used.In order to determine what remote branches to fetch (and optionally store in the remote-tracking branches) when the command is run without any refspec parameters on the command line, values of the configuration variable remote.<origin>.fetch are consulted, and if there aren’t any, $GIT_DIR/remotes/<origin> is consulted and its Pull: lines are used. In addition to the refspec formats described in the OPTIONS section, you can have a globbing refspec that looks like this:refs/heads/*:refs/remotes/origin/*A globbing refspec must have a non-empty RHS (i.e. must store what were fetched in remote-tracking branches), and its LHS and RHS must end with /*. The above specifies that all remote branches are tracked using remote-tracking branches in refs/remotes/origin/ hierarchy under the same name.The rule to determine which remote branch to merge after fetching is a bit involved, in order not to break backward compatibility.If explicit refspecs were given on the command line of git pull, they are all merged.When no refspec was given on the command line, then git pull uses the refspec from the configuration or $GIT_DIR/remotes/<origin>. In such cases, the following rules apply:

• If branch.<name>.merge configuration for the current branch <name> exists, that is the name of the branch at the remote site that is merged.

1. If the refspec is a globbing one, nothing is merged.

1. Otherwise the remote branch of the first refspec is merged.

Examples

• Update the remote-tracking branches for the repository you cloned from, then merge one of them into your current branch:  $ git pull $ git pull originNormally the branch merged in is the HEAD of the remote repository, but the choice is determined by the branch.<name>.remote and branch.<name>.merge options; see git-config[1] for details.

• Merge into the current branch the remote branch next:

$ git pull origin next

This leaves a copy of next temporarily in FETCH_HEAD, but does not update any remote-tracking branches. Using remote-tracking branches, the same can be done by invoking fetch and merge:

$ git fetch origin $ git merge origin/next

If you tried a pull which resulted in complex conflicts and would want to start over, you can recover with git reset.

Security

The fetch and push protocols are not designed to prevent one side from stealing data from the other repository that was not intended to be shared. If you have private data that you need to protect from a malicious peer, your best option is to store it in another repository. This applies to both clients and servers. In particular, namespaces on a server are not effective for read access control; you should only grant read access to a namespace to clients that you would trust with read access to the entire repository.

The known attack vectors are as follows:

1. The victim sends "have" lines advertising the IDs of objects it has that are not explicitly intended to be shared but can be used to optimize the transfer if the peer also has them. The attacker chooses an object ID X to steal and sends a ref to X, but isn’t required to send the content of X because the victim already has it. Now the victim believes that the attacker has X, and it sends the content of X back to the attacker later. (This attack is most straightforward for a client to perform on a server, by creating a ref to X in the namespace the client has access to and then fetching it. The most likely way for a server to perform it on a client is to "merge" X into a public branch and hope that the user does additional work on this branch and pushes it back to the server without noticing the merge.)

1. As in #1, the attacker chooses an object ID X to steal. The victim sends an object Y that the attacker already has, and the attacker falsely claims to have X and not Y, so the victim sends Y as a delta against X. The delta reveals regions of X that are similar to Y to the attacker.

Bugs

Using --recurse-submodules can only fetch new commits in already checked out submodules right now. When e.g. upstream added a new submodule in the just fetched commits of the superproject the submodule itself can not be fetched, making it impossible to check out that submodule later without having to do a fetch again. This is expected to be fixed in a future Git version.

See also

git-fetch[1], git-merge[1], git-config[1]