English ▾ 主題 ▾ 最新版本 ▾ git-remote 最後更新於 2.53.0

名稱

git-remote - 管理追蹤的儲存庫集合

概要

git remote [-v | --verbose]
git remote add [-t <branch>] [-m <master>] [-f] [--[no-]tags] [--mirror=(fetch|push)] <name> <URL>
git remote rename [--[no-]progress] <old> <new>
git remote remove <name>
git remote set-head <name> (-a | --auto | -d | --delete | <branch>)
git remote set-branches [--add] <name> <branch>…​
git remote get-url [--push] [--all] <name>
git remote set-url [--push] <name> <newurl> [<oldurl>]
git remote set-url --add [--push] <name> <newurl>
git remote set-url --delete [--push] <name> <URL>
git remote [-v | --verbose] show [-n] <name>…​
git remote prune [-n | --dry-run] <name>…​
git remote [-v | --verbose] update [-p | --prune] [(<group> | <remote>)…​]

描述

管理您所追蹤分支的儲存庫（即「遠端」）集合。

選項

-v
--verbose

更詳細顯示資訊，在名稱後顯示遠端 URL。對於約定（promisor）遠端，同時顯示已設定的篩選器（如 blob:none 等）。注意：此選項必須置於 remote 與子指令之間。

指令

若無任何參數，則列出現有的遠端儲存庫。可以使用多個子指令對遠端儲存庫進行操作。

add

為位於 <URL> 的儲存庫新增一個名為 <name> 的遠端。之後即可使用 git fetch <name> 指令來建立並更新遠端追蹤分支 <name>/<branch>。

使用 -f 選項時，會在設定遠端資訊後立即執行 git fetch <name>。

使用 --tags 選項時，git fetch <name> 會匯入遠端儲存庫中的所有標籤。

使用 --no-tags 選項時，git fetch <name> 不會匯入遠端儲存庫中的標籤。

預設情況下，僅匯入已抓取（fetch）分支上的標籤（請參閱 git-fetch[1]）。

使用 -t <branch> 選項時，將建立一個僅追蹤 <branch> 的參照規格（refspec），而非預設追蹤 refs/remotes/<name>/ 命名空間下所有分支的萬用字元參照規格。您可以提供多個 -t <branch> 以追蹤多個分支，而無需抓取所有分支。

使用 -m <master> 選項時，會設定一個符號參照（symbolic-ref）refs/remotes/<name>/HEAD 指向遠端的 <master> 分支。另請參閱 set-head 指令。

當使用 --mirror=fetch 建立抓取鏡像時，參照不會儲存在 refs/remotes/ 命名空間中，而是遠端 refs/ 下的所有內容會直接鏡像到本地儲存庫的 refs/ 中。此選項僅適用於純（bare）儲存庫，因為抓取操作會覆蓋任何本地提交。

當使用 --mirror=push 建立推送鏡像時，git push 的行為將始終如同執行了 --mirror 一樣。

rename

將名為 <old> 的遠端重新命名為 <new>。該遠端的所有遠端追蹤分支與設定值都會隨之更新。

若 <old> 與 <new> 相同，且 <old> 是位於 $GIT_DIR/remotes 或 $GIT_DIR/branches 下的一個檔案，則該遠端會被轉換為設定檔格式。

remove
rm

移除名為 <name> 的遠端。該遠端的所有遠端追蹤分支與設定值都會被移除。

set-head

設定或刪除指定遠端的預設分支（即符號參照 refs/remotes/<name>/HEAD 的目標）。遠端不一定要有預設分支，但若有設定，則在指定分支時可用遠端名稱代替具體分支。例如，若 origin 的預設分支設為 master，那麼在通常指定 origin/master 的地方，皆可使用 origin。

使用 -d 或 --delete 時，符號參照 refs/remotes/<name>/HEAD 將被刪除。

使用 -a 或 --auto 時，會查詢遠端以確定其 HEAD，然後將符號參照 refs/remotes/<name>/HEAD 設定為相同的分支。例如，若遠端 HEAD 指向 next，執行 git remote set-head origin -a 會將符號參照 refs/remotes/origin/HEAD 設定為 refs/remotes/origin/next。這僅在 refs/remotes/origin/next 已存在時有效；若不存在，必須先進行抓取（fetch）。

使用 <branch> 明確設定符號參照 refs/remotes/<name>/HEAD。例如，git remote set-head origin master 會將符號參照 refs/remotes/origin/HEAD 設定為 refs/remotes/origin/master。這僅在 refs/remotes/origin/master 已存在時有效；若不存在，必須先進行抓取。

set-branches

變更由該遠端所追蹤的分支列表。此指令可用於在遠端初始設定後，變更追蹤的遠端分支子集。

指定的這些分支將被視為如同在 git remote add 指令列中使用 -t 選項指定一樣。

使用 --add 時，不會取代目前的追蹤分支列表，而是將新分支加入該列表。

get-url

擷取遠端的 URL。此處會展開 insteadOf 與 pushInsteadOf 的設定。預設僅列出第一個 URL。

使用 --push 時，會查詢推送 URL 而非抓取 URL。

使用 --all 時，將列出該遠端的所有 URL。

set-url

變更遠端的 URL。將遠端 <name> 中符合正規表示式 <oldurl> 的第一個 URL（若未給定 <oldurl> 則為第一個 URL）設定為 <newurl>。若 <oldurl> 不符合任何 URL，則會發生錯誤且不進行變更。

使用 --push 時，操作的是推送 URL 而非抓取 URL。

使用 --add 時，不會變更現有的 URL，而是新增一個新的 URL。

使用 --delete 時，不會變更現有的 URL，而是刪除遠端 <name> 中所有符合正規表示式 <URL> 的 URL。嘗試刪除所有非推送 URL 會導致錯誤。

請注意，推送 URL 與抓取 URL 即使可以設為不同，它們仍必須指向同一個位置。推送到推送 URL 的內容應與立即從抓取 URL 進行抓取時所看到的內容一致。如果您打算從某處抓取（例如上游），並推送到另一個地方（例如您的發佈儲存庫），請使用兩個不同的遠端。

show

提供關於遠端 <name> 的資訊。

使用 -n 選項時，不會先透過 git ls-remote <name> 查詢遠端分支，而是直接使用快取的資訊。

prune

刪除與 <name> 相關的過時參照。預設會刪除 <name> 下過時的遠端追蹤分支，但根據全域設定與該遠端的設定，甚至可能會修剪（prune）未推送到該處的本地標籤。等同於 git fetch --prune <name>，但不會抓取任何新的參照。

關於根據不同設定會修剪哪些內容，請參閱 git-fetch[1] 的 PRUNING 章節。

使用 --dry-run 選項時，會報告將會被修剪的分支，但不會實際執行修剪。

update

抓取儲存庫中由 remotes.<group> 定義的遠端或遠端群組的更新。若指令列中未指定群組或遠端，則會使用設定參數 remotes.default；若未定義 remotes.default，則會更新所有未將設定參數 remote.<name>.skipDefaultUpdate 設為 true 的遠端。（請參閱 git-config[1]）。

使用 --prune 選項時，會對所有更新的遠端執行修剪操作。

討論

遠端設定是透過 remote.origin.url 與 remote.origin.fetch 設定變數來實現的。（請參閱 git-config[1]）。

結束狀態

成功時，結束狀態為 0。

當 add、rename 與 remove 等子指令無法找到對應的遠端時，結束狀態為 2。當遠端已存在時，結束狀態為 3。

在任何其他錯誤情況下，結束狀態可能是其他非零值。

範例

  • 新增一個遠端、抓取並檢出（check out）其中的一個分支

    $ git remote
origin
$ git branch -r
  origin/HEAD -> origin/master
  origin/master
$ git remote add staging git://git.kernel.org/.../gregkh/staging.git
$ git remote
origin
staging
$ git fetch staging
...
From git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging
 * [new branch]      master     -> staging/master
 * [new branch]      staging-linus -> staging/staging-linus
 * [new branch]      staging-next -> staging/staging-next
$ git branch -r
  origin/HEAD -> origin/master
  origin/master
  staging/master
  staging/staging-linus
  staging/staging-next
$ git switch -c staging staging/master
...

  • 模擬 git clone 但僅追蹤選定的分支

    $ mkdir project.git
$ cd project.git
$ git init
$ git remote add -f -t master -m master origin git://example.com/git.git/
$ git merge origin

參見

git-fetch[1] git-branch[1] git-config[1]

GIT

git[1] 套件的一部分