English ▾ 主題 ▾ 最新版本 ▾ git-archive 最後更新於 2.54.0

名稱

git-archive - 從指定的樹狀物件建立檔案封存檔

概要

git archive [--format=<fmt>] [--list] [--prefix=<prefix>/] [<extra>]
	      [-o <file> | --output=<file>] [--worktree-attributes]
	      [--remote=<repo> [--exec=<git-upload-archive>]] <tree-ish>
	      [<path>…​]

描述

建立一個包含指定樹狀物件結構的封存檔，格式依指定，並寫入標準輸出。若指定了 <prefix>，則會將其加在封存檔內各檔名的開頭。

git archive 在處理樹狀物件識別碼（tree ID）與處理提交識別碼（commit ID）或標籤識別碼（tag ID）時行為不同。當提供樹狀物件識別碼時，封存檔中每個檔案的修改時間將設為當前時間。另一方面，當提供提交識別碼或標籤識別碼時，則使用參考的提交物件中所記錄的提交時間。此外，若使用 tar 格式，提交識別碼會儲存在全域擴充 pax 表頭中；可以使用 git get-tar-commit-id 來提取。在 ZIP 檔案中，它會被儲存為檔案註解。

選項

--format=<fmt>

結果封存檔的格式。可能的值包括 tar、zip、tar.gz、tgz，以及任何使用設定選項 tar.<format>.command 所定義的格式。若未提供 --format，且指定了輸出檔案，則會盡可能從檔名推斷格式（例如，寫入 foo.zip 會使輸出採用 zip 格式）。否則，預設輸出格式為 tar。

-l
--list

顯示所有可用的格式。

-v
--verbose

向 stderr 回報進度。

--prefix=<prefix>/

將 <prefix>/ 加在封存檔內路徑的前面。可以重複使用；最右側的值會用於所有被追蹤的檔案。請參見下文關於 --add-file 會使用哪個值的說明。

<prefix> 會直接使用而不會正規化。它可能包含開頭的斜線或上層目錄元件（例如 ../）。某些封存檔取用工具可能會將此類路徑視為潛在不安全，並在解壓縮時進行調整或發出警告。

-o <file>
--output=<file>

將封存檔寫入 <file> 而非標準輸出。

--add-file=<file>

將未追蹤的檔案加入封存檔。可以重複使用以加入多個檔案。封存檔內的檔案路徑由該 --add-file 之前最後一個 --prefix 選項的值（若有）加上 <file> 的基底名稱（basename）組合而成。

--add-virtual-file=<path>:<content>

將指定的內容加入封存檔。可以重複使用以加入多個檔案。

<path> 引數的開頭和結尾可以包含字面上的雙引號字元；其中的檔案名稱會被解釋為 C 風格字串，即反斜線會被解釋為跳脫字元。若路徑包含冒號（為了避免冒號被誤判為路徑與內容的分隔符）或路徑以雙引號開頭或結尾，則必須將路徑括起來。

檔案模式僅限於一般檔案，且此選項可能受限於平台相關的命令列長度限制。對於複雜的情況，請先寫入一個未追蹤的檔案，然後改用 --add-file。

請注意，與 --add-file 不同，封存檔內建立的路徑不受 --prefix 選項影響，因為完整的 <path> 可直接作為該選項的值。

--worktree-attributes

同時在工作目錄中的 .gitattributes 檔案中尋找屬性（請參見 屬性 (ATTRIBUTES)）。

--mtime=<time>

設定封存檔項目的修改時間。若無此選項，當 <tree-ish> 為提交或標籤時使用提交者時間，若為樹狀物件則使用當前時間。

<extra>

這可以是封存後端能理解的任何選項。請參見下一節。

--remote=<repo>

不從本機儲存庫製作 tar 封存檔，而是從遠端儲存庫擷取。請注意，遠端儲存庫可能會限制 <tree-ish> 中允許使用的 sha1 表達式。詳情請見 git-upload-archive[1]。

--exec=<git-upload-archive>

與 --remote 一起使用，以指定遠端側 git-upload-archive 的路徑。

<tree-ish>

要產生封存檔的樹狀物件或提交物件。

<path>

若無選填的路徑參數，目前工作目錄的所有檔案和子目錄都會包含在封存檔中。若指定了一個或多個路徑，則僅包含這些路徑。

後端額外選項 (BACKEND EXTRA OPTIONS)

zip

-<digit>

指定壓縮等級。較大的數值表示命令會花費更多時間以達到較小的體積。支援的值從 -0（僅儲存）到 -9（最佳比例）。若未給定，預設為 -6。

tar

-<number>

指定壓縮等級。該數值會傳遞給在 tar.<format>.command 中設定的壓縮命令。請參閱該設定命令的手冊頁以查看支援的等級列表以及若未指定此選項時的預設等級。

組態設定 (CONFIGURATION)

tar.umask

此變數可用於限制 tar 封存檔項目的權限位元。預設值為 0002，會關閉全域寫入位元。特殊值 "user" 表示改用封存使用者的 umask。詳情請見 umask(2)。若使用了 --remote，則僅遠端儲存庫的設定生效。

tar.<format>.command

此變數指定一個 shell 命令，git archive 產生的 tar 輸出應透過管線導向該命令。該命令會使用 shell 執行，並將產生的 tar 檔案作為其標準輸入，並應在標準輸出產生最終結果。任何壓縮等級選項都會傳遞給此命令（例如 -9）。

tar.gz 和 tgz 格式是自動定義的，預設使用神奇命令 git archive gzip，它會呼叫內建的 gzip 實作。

tar.<format>.remote

若為 true，則啟用該格式供遠端用戶端透過 git-upload-archive[1] 使用。對於使用者自訂格式預設為 false，但對於 tar.gz 和 tgz 格式預設為 true。

屬性 (ATTRIBUTES)

export-ignore

具有 export-ignore 屬性的檔案和目錄不會被加入封存檔。詳情請見 gitattributes[5]。

export-subst

若檔案設定了 export-subst 屬性，當將該檔案加入封存檔時，Git 會展開其中的數個佔位符。詳情請見 gitattributes[5]。

請注意，屬性預設取自封存檔所屬樹狀結構中的 .gitattributes 檔案。如果您想在事後調整輸出產生方式（例如您在沒有於 .gitattributes 中正確加入 export-ignore 的情況下進行了提交），請視需要調整已檢出的 .gitattributes 檔案，並使用 --worktree-attributes 選項。或者，您可以將封存任何樹狀結構時應適用的必要屬性保留在您的 $GIT_DIR/info/attributes 檔案中。

範例

git archive --format=tar --prefix=junk/ HEAD | (cd /var/tmp/ && tar xf -)

建立一個包含目前分支最新提交內容的 tar 封存檔，並將其解壓縮至 /var/tmp/junk 目錄中。

git archive --format=tar --prefix=git-1.4.0/ v1.4.0 | gzip >git-1.4.0.tar.gz

為 v1.4.0 發行版本建立壓縮的 tarball。

git archive --format=tar.gz --prefix=git-1.4.0/ v1.4.0 >git-1.4.0.tar.gz

同上，但使用內建的 tar.gz 處理方式。

git archive --prefix=git-1.4.0/ -o git-1.4.0.tar.gz v1.4.0

同上，但格式是從輸出檔案名稱推斷出來的。

git archive --format=tar --prefix=git-1.4.0/ v1.4.0^{tree} | gzip >git-1.4.0.tar.gz

為 v1.4.0 發行版本建立一個壓縮的 tarball，但不包含全域擴充 pax 表頭。

git archive --format=zip --prefix=git-docs/ HEAD:Documentation/ > git-1.4.0-docs.zip

將目前 HEAD 的 Documentation/ 目錄中的所有內容放入 git-1.4.0-docs.zip，並加上 git-docs/ 前綴。

git archive -o latest.zip HEAD

建立一個包含目前分支最新提交內容的 Zip 封存檔。請注意，輸出格式是由輸出檔案的副檔名所推斷的。

git archive -o latest.tar --prefix=build/ --add-file=configure --prefix= HEAD

建立一個 tar 封存檔，其中包含目前分支最新提交的內容（無前綴），以及具有 build/ 前綴的未追蹤檔案 configure。

git config tar.tar.xz.command "xz -c"

設定用於製作 LZMA 壓縮 tar 檔案的 "tar.xz" 格式。您可以透過指定 --format=tar.xz 或建立如 -o foo.tar.xz 的輸出檔案來使用它。

參見

gitattributes[5]

GIT

git[1] 套件的一部分