> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# xbCopy (xbcopy.exe)

> xbCopy (xbcopy.exe)

使用此工具在開發主機之間執行差異檔案複製。

| 欄 1 |
| - |
| **xbcopy** *source* *destination* \[search\_pattern\[...]] \[*options*] \[/s\[:]*levels*] \[/X\[:]*address\[+\<accesskey>]*] |

| 選項 | 描述 |
| - | - |
| *source* | 來源目錄路徑 |
| *destination* | 目的地目錄路徑 |
| *search\_pattern* | 指定要複製的檔案或搜尋模式 (支援萬用字元 \* 與 ?)。如果您未指定此參數，則會使用 \* 作為預設值。搜尋模式以空格分隔，並可包含檔案的連結，例如 xbcopy.exe c:\mysource xD:\console\path \*.png \*.txt specific\_file.json |
| *options* | 指定要與 xbcopy 命令一起使用的選項，包括複製、模式與記錄選項。 |
| /s:\[levels] | 複製指定目錄及其所有子目錄中的檔案。levels 是選擇性整數，指定子目錄的遞迴深度。例如，/s:1 只會處理指定的目錄及其下一層的子目錄。如果指定了 /s 但未指定 levels，則會包含所有子目錄。 |
| /X\[:]*address\[+\<accesskey>]* | - 使用此選項可指定目標主機的主機名稱或位址 (在主機上顯示為 **Tools IP**)，而不需變更預設主機。如需為主機設定主機名稱的詳細資訊，請參閱[為主機 IP 位址設定主機名稱](/zh-TW/home/setup-install/dev-kit-settings/setting-a-hostname)。 - 如果您不使用此選項，則會使用預設主機 (先前由[連線 (xbconnect.exe)](/zh-TW/tools/tools-console/commandlinetools/xbconnect) 設定)。 - 使用 *accesskey* 字串，只為擁有存取金鑰的人員提供主機存取權。 - 使用 **xbconfig accesskey=your-key** 命令設定存取金鑰，然後重新啟動主機，讓存取金鑰生效。 - 若要存取已設定存取金鑰的主機，您必須在主機的 IP 位址或主機名稱後面加上加號 (+) 與存取金鑰。 - 如果在使用 [xbconnect](/zh-TW/tools/tools-console/commandlinetools/xbconnect) 設定預設主機時提供了存取金鑰，該存取金鑰會儲存為預設主機位址的一部分。 - 如需存取金鑰的詳細資訊，請參閱 [xbconfig accesskey](/zh-TW/tools/tools-console/commandlinetools/xbconfig)。 |
| /LC | 指定地區設定代碼。用於覆寫預設的地區設定代碼 |

### 複製模式

複製模式彼此互斥，每個複製作業只能指定一種。如果未指定複製模式，工具會檢查檔案是否已修改，只有已修改的檔案才會納入複製作業。

| 選項 | 描述 | 篩選支援 | 搜尋模式支援 |
| - | - | - | - |
| /list | 列舉或列出所有將被複製的檔案，可作為複製預覽。 | 是 | 是 |
| /overwrite | 如果選取此項，工具不會檢查檔案是否已修改，因此所有檔案都會被覆寫。 | 是 | 是 |
| /mirror | 刪除來源中已不存在的目的地檔案與目錄。如果指定此模式，就無法指定搜尋模式與篩選選項。 | 否 | 否 |

### 篩選選項

這些選項可讓使用者透過篩選條件，指定哪些檔案與目錄要納入複製。此工具提供兩種類型的篩選條件：

* 殼層命令篩選條件 (/exd、/exf/ /ina 與 /exa)。
* JSON 檔案篩選條件 (/rules)

| 選項 | 描述 |
| - | - |
| /exf \[*file-name*] \[…] | 排除符合指定名稱或路徑的檔案。支援萬用字元 \* 與 ?。例如：*xbcopy src dst /s /exf \*.png \*.data* 會排除所有副檔名為 png 與 data 的檔案。 |
| /exd \[*directory-name*] \[…] | 排除符合指定名稱與路徑的目錄。支援萬用字元 \* 與 ?。例如：*xbcopy src dst /s /exd *assets** 會排除名稱中包含 assets 一詞的任何目錄，不予複製。 |
| /ina:\[R]\[A]\[S]\[H] | 只包含已設定任何指定屬性的檔案。支援的有效包含選項為 *R* (唯讀)、*A* (封存)、*S* (系統) 與 *H* (隱藏) |
| /exa:\[R]\[A]\[S]\[H] | 排除已設定任何指定屬性的檔案。支援的有效排除選項為 *R* (唯讀)、*A* (封存)、*S* (系統) 與 *H* (隱藏) |
| /rules:\[*file\_name*] | 指定 JSON 檔案，以提供比殼層命令參數更強大的檔案/目錄排除/包含篩選功能。如需檔案格式的詳細資訊，請參閱 [JSON 規則檔格式](#json-rule-file-format)一節。 |

### 記錄選項

xbCopy 提供下列記錄選項：

| 選項 | 描述 |
| - | - |
| /nlh | 記錄中不包含標頭 |
| /nlc | 記錄中不包含檔案欄標題 |
| /nlsi | 記錄中不包含檔案大小 |
| /nlst | 記錄中不包含檔案複製狀態 |
| /nlsu | 記錄中不包含摘要 |
| /nlp | 記錄中不包含複製進度 |
| /nlf | 記錄中不包含檔案名稱 |

### JSON 規則檔格式

此檔案由兩個 JSON 規則物件陣列組成。您可以視需要指定其中一個或兩個。
一個陣列包含指定哪些檔案或目錄要從複製作業中排除的規則，另一個陣列則包含指定哪些檔案或目錄要納入的規則。

需要考量的事項：

* 要排除或包含的檔案或目錄，必須分別符合各陣列中至少一個規則。
* 如果排除某個目錄，其所有子目錄也會一併排除。
* 如果未指定任何包含規則，則所有檔案與目錄都會納入複製，除非它們符合其中一個排除規則。
* 排除規則優先，因此如果檔案或目錄同時符合包含與排除規則，則會被排除。
* 在一個陣列中，規則會依序套用。這表示您在陣列中最先定義的規則會最先檢查。

以下是 JSON 規則檔的一般語法格式：

```
{
        "ExcludeRules" : [rule_1, rule_2, rule_3, …, rule_N],
        "IncludeRules"  : [rule_1, rule_2, rule_3, …, rule_N]
}
```

#### 規則格式

規則物件至少由兩個屬性組成：搜尋模式 (萬用字元或規則運算式) 與 ApplyTo。Path 屬性是選擇性的。以下是每個屬性的描述。

| 屬性 | 描述 | 必要 (請參閱備註) |
| - | - | - |
| "Wildcard" | 指定萬用字元搜尋模式，檔案或目錄必須符合此模式，才會依規則所在位置被視為包含或排除。萬用字元搜尋模式中只支援 \* 與 ?。 | 是 |
| "Regex" | 指定規則運算式搜尋模式，檔案或目錄必須符合此模式，才會依規則所在位置被視為包含或排除。 | 是 |
| "ApplyTo" | 指定規則範圍，也就是規則只套用至檔案、只套用至目錄，還是兩者皆套用。有效值為 "File"、"Directory" 或 "Both" | 是 |
| "Path" | 指定搜尋模式要套用的對象，可以是完整路徑、相對路徑或單一名稱。如果未提供此參數，則會假設為完整路徑。有效值為 "Full"、"Relative" 或 "Name" | 否 |

> 注意：Wildcard 與 Regex 屬性不能同時用於同一個規則，每個規則一次只能指定其中一個。定義與安排規則位置時請小心，特別是規則之間有重疊時。

### JSON 規則檔範例

#### 範例 1：排除檔案與目錄的規則檔格式。

下列檔案會：

* 排除副檔名為 .xml 與 .exe 的檔案
* 排除名稱等於 "assets" 的任何目錄

```
{
        "ExcludeRules" : 
        [
                {
                        "Wildcard" : "*.xml",
                        "ApplyTo"  : "File"
                },
                {
                        "Wildcard" : "assets",
                        "ApplyTo"  : "Directory", 
                        "Path"        : "Name"
                },
                {
                        "Regex"      : "^.*\\.exe$",
                        "ApplyTo"  : "File",
                        "Path"        : "Name"
                }
        ],

        "IncludeRules" : []
}
```

#### 範例 2：指定必須複製哪些檔案與目錄的規則檔格式。

此規則檔格式只會複製副檔名為 .exe 與 .data 的檔案

```
{
        "ExcludeRules" : [],
        "IncludeRules" : 
        [
                {
                        "Wildcard" : "*.exe",
                        "ApplyTo"  : "File"
                },
                {
                        "Wildcard" : "*.data",
                        "ApplyTo"  : "File"
                }
        ]
}
```

### xbCopy 範例

| 範例 | 描述 |
| - | - |
| xbcopy c:\mysource xD:\Some\RemoteFolder \*.png /s | 單一搜尋模式與所有子目錄 |
| xbcopy c:\mysource xD:\Some\RemoteFolder \*.png /s:2 | 單一搜尋模式，子目錄深度為兩層 |
| xbcopy c:\mysource xD:\Some\RemoteFolder \*.png \*.txt \*.log /s | 多個搜尋模式 |
| xbcopy c:\mysource xD:\Some\RemoteFolder /exd *data* | 單一排除目錄 |
| xbcopy c:\mysource xD:\Some\RemoteFolder /s /exd *data* *bin* | 多個排除目錄 |
| xbcopy c:\mysource xD:\Some\RemoteFolder /s /exf \*.xml | 單一排除檔案篩選條件 |
| xbcopy c:\mysource xD:\Some\RemoteFolder /s /exf specific\_file.ext \*.mp? | 多個排除檔案 |
| xbcopy c:\mysource xD:\Some\RemoteFolder /s /rules:filter.json | 使用 JSON 規則檔套用篩選條件 |
| xbcopy c:\mysource xD:\Some\RemoteFolder /s /rules:filter.json /list | 套用清單複製模式以預覽複製 |

## 另請參閱

[命令列工具](/zh-TW/tools/tools-console/commandlinetools/commandlinetools)

[檔案複製](/zh-TW/tools/tools-console/commandlinetools/xbcp)

[XTF 傳輸錯誤](/zh-TW/tools/tools-console/commandlinetools/xtf-transport-errors)


## Related topics

- [主機開發的命令列工具](/zh-TW/tools/tools-console/commandlinetools/commandlinetools.md)
- [命令列工具](/zh-TW/tools/tools-console/commandlinetools/index.md)
- [GDK 名詞與縮寫詞彙表](/zh-TW/home/glossary.md)
- [xbWatson](/zh-TW/tools/tools-console/xbWatson/xbwatson.md)
- [版本資訊 (xbVersionInfo.exe)](/zh-TW/tools/tools-console/commandlinetools/xbversioninfo.md)