共用方式為


適用於 Microsoft Learn 的 Git 和 GitHub 基本概念檔

概觀

身為 Microsoft Learn 檔的參與者,您將與多個工具和程序互動。 您會同時與其他貢獻者在相同專案上共同作業,而且甚至可能同時處理相同內容。 這一切都是透過 Git 和 GitHub 軟體來達成。

Git 是一個開放原始碼的版本控制系統。 它透過「存放庫」中之檔案的「分散式版本控制」來促成此類型的專案共同作業。 本質上來說,Git 可整合由多個參與者在不同時間,針對指定的存放庫所完成的工作流。

GitHub 是 Git 存放庫的 Web 型裝載服務,例如用來儲存 Microsoft Learn 內容的存放庫。 針對任何專案,GitHub 都裝載主要存放庫,供貢獻者針對其自己的工作建立複本

本文定義屬於 Microsoft Learn 工作流程的重要詞彙。 它也提供 Git 和 GitHub 存放庫的概觀,並說明如何針對 Microsoft 技術文件組織內容。

分支

分支會分隔工作串流 (通常稱為版本)。 貢獻一律是在特定分支的範圍所進行。

隔離特定分支的相關變更可讓您獨立控制及引進這些變更。 在現實中,根據所進行工作的不同,您的存放庫中很容易就會出現數個工作分支。 同時處理多個分支 (每個分支都代表不同的專案) 的情況,其實相當常見。

所有存放庫都包含預設分支(通常命名為 “main”),以及一或多個進行中分支(我們稱之為工作分支),尚未整合到預設分支中。 預設分支可作為專案的目前版本和「單一事實來源」。 它是存放庫中所有其他分支的建立來源。

每次您引進一組新的邏輯相關變更時,最佳做法是建立工作分支來管理您的變更。 不建議直接變更預設分支。

分支

當參考主要 GitHub 存放庫的複本時,此詞彙通常用來作為名詞。 實際上,分叉只是另一個存放庫。 但它的特殊之處在於 GitHub 會維護與主要/父存放庫之間的關係。 此字詞有時會當做動詞使用,如「您必須先分叉存放庫」。

Git

如果您熟悉集中式版本控制系統(例如 Team Foundation Server、SharePoint 或 Visual Source 保管庫),您會發現 Git 有獨特的貢獻工作流程和術語來支援其分散式模型。 例如,沒有通常與簽出/簽入作業相關聯的檔案鎖定。 相反地,Git 會考慮更精細層級的變更,比較檔案位元組位元組。

Git 也使用分層結構來儲存及管理專案內容:

  • 存放庫:亦稱為 repo,這是最高的儲存單位。 存放庫包含一或多個分支。
  • 分支:包含組成專案內容集合之檔案與資料夾的儲存單位。 如需分支的詳細資訊,請參閱 本文的分支 一節。

參與者會與 Git 互動,以在本機和 GitHub 層級對存放庫進行更新和操作:

  • 在本機透過 Git Bash 主控台這類工具,而這類工具支援用來管理本機存放庫以及與 GitHub 存放庫通訊的 Git 命令。
  • 透過 www.github.com,而此網站整合 Git,以管理協調流回主要存放庫的參與。

GitHub

注意

雖然檔指引是以使用 GitHub 為基礎,但有些小組會使用 Visual Studio Team Services 來裝載 Git 存放庫。 Visual Studio Team Explorer 用戶端提供用來與 Team Services 存放庫互動的 GUI,做為透過命令列使用 Git 命令之外的替代方法。
此外,下列許多指導方針都是從在 GitHub 中裝載 Azure 服務內容的多年經驗中開發為最佳做法。 某些 Microsoft Learn 存放庫中可能需要這些存放庫。

所有工作流程都會在 GitHub 層級開始和結束,其中儲存任何文件專案的主要存放庫。 參與者為自己的使用目的而建立的複本會跨多部電腦散佈。 這些複本最終會協調回專案的主要 GitHub 存放庫。

目錄組織方式

項目的預設分支可作為專案的目前內容版本。 默認分支中的內容,以及從中建立的分支,會鬆散地與對應 Microsoft Learn 頁面上文章的組織對齊。 子目錄可用來分隔類似文章(例如服務)、媒體內容(例如圖像檔)和「包含」檔案(可重複使用內容)。

Articles 子目錄

您通常可以在存放庫的根目錄找到主要 articles 目錄。 目錄articles包含子目錄中的一組子目錄 Articles,會格式化為使用 .md 擴展名的 Markdown 檔案。 某些支援多個服務的存放庫會使用一般的 /articles 子目錄 (例如 Azure-Docs 存放庫)。 其他存放庫可能會使用服務特定的名稱 (例如使用 /IntuneDocsIntuneDocs 存放庫)。

在此目錄的根內,您可以找到有關整體服務或產品的一般文章。 您通常也可以接著找到另一系列的子目錄,這些子目錄會符合功能/服務或常見案例。 例如,Azure "virtual machine" (虛擬機器) 文章是位於 /virtual-machines 子目錄,而 Intune "understand and explore" (了解與探索) 文章則位於 /understand-explore 子目錄。

Media 子目錄

每個 article 目錄都包含對應之媒體檔案的 /media 子目錄。 媒體檔案包含具有影像參考之文章所使用的影像。

Includes 子目錄

只要有兩篇或多篇文章共用的可重複使用內容,系統就會將它放置在主要 articles 目錄的 /includes 子目錄中。 在使用 include 檔案的 Markdown 檔案中,系統會將對應的 "include" Markdown 擴充功能放置在需要參考 include 檔案的位置。

請參閱 Markdown 參考:包含 以取得其他指引。

Markdown 檔案範本

為了方便起見,每個存放庫的根目錄通常包含一個名為 template.md 的 Markdown 檔案。 若需要建立新文章以提交到存放庫,您可以將此範本檔案做為「開始檔案」使用。 檔案包含:

  • 檔案頂端的中繼資料標頭其中包含兩個具有 3 個破折號的行。 它包含用於與文章相關之追蹤資訊的多種標記。 文章中繼資料可啟用特定功能,例如作者姓名標示、參與者姓名標示、階層連結與文章描述。 它也包括 SEO 最佳化與報告程序,Microsoft 使用它們來評估內容的成效。 因此,中繼資料非常重要!
  • 能描述各種中繼資料標記和值的中繼資料區段。 如果您不確定在中繼資料區段中應使用的值,則可以留白,或在前面加上雜湊標記 (#) 使其成為註解,讓存放庫的提取要求檢閱者來檢閱/完成它們。
  • 各種使用「Markdown 來格式化文章元素的範例」
  • 一般的Markdown 擴充功能使用指示,可用於各種類型的警示。
  • 使用 iframe 內嵌視訊的範例。
  • 使用 Microsoft 技術檔延伸模組的一般指示,可用於特殊控件,例如按鈕和選取器。

原始來源

此字詞是指派給本機存放庫與其複製位置之存放庫之間的連線名稱。 在 Microsoft Learn 工作流程中,原點代表您分支的連線。 此詞彙有時會作為來源存放庫本身的Moniker,如「記得將變更推送至來源」一樣。

提取要求

提取 要求 (PR) 是要求內容擁有者將變更提取至官方來源的要求。 PR 可讓 GitHub 的共同作業模型,要求將工作分支中的變更(也稱為 認可)提取並合併至另一個分支。 在大部分情況下,其他分支是主要存放庫中的預設分支。

PR 也可作為機制,在變更合併至預設分支之前,提供來自 Microsoft Learn 驗證程式的意見反應給參與者,以及 PR 檢閱者來解決問題或問題。

遠端

遠端是遠端存放庫的具名連線,例如「來源」或「上游」遠端。 Git 將此稱為遠端,因為它用來參考另一部計算機上裝載的存放庫。 在 Microsoft Learn 工作流程中,遠端一律是 GitHub 存放庫。

上游

如同來源遠端, 上游 是另一個存放庫的具名連線。 在 Microsoft Learn 工作流程中,上游代表本機存放庫與建立分支的主要存放庫之間的連線。 這個詞彙有時會當做上游存放庫本身的Moniker使用,如「記得從上游提取最新的變更」一樣。

深入了解

如果您不熟悉 Git 或 GitHub,這些資源可協助您瞭解、提高生產力或回答問題。

Git 原始檔控制資源

GitHub 資源

常見問題集

什麼是 Git?

當許多人一起處理計算機程式代碼時,Git 有助於追蹤變更。 這就像是程式代碼的時間機器,因此您可以查看變更的專案,並視需要返回。

為什麼要使用 Git?

這非常適合團隊合作。 Git 可讓很多人輕鬆地處理同一個專案,而不會讓彼此的工作混亂。 它也有助於輕鬆地修正錯誤。

Git 如何運作?

Git 會儲存專案程式代碼的所有版本。 當您進行變更時,Git 會拍攝不同內容的照片(例如快照集)。 您可以同時建立不同的版本,而不會發生問題。

Git 中的分支為何?

分支就像專案中的不同路徑。 他們讓人們在不變更主要項目的情況下處理新事物。 稍後,他們可以將這些變更帶回主要專案。

Git 中的認可為何?

認可就像儲存點。 這是記錄您所做的變更的一種方式。 每個認可都有唯一標識符,以及變更內容的相關附注。

什麼是 GitHub?

GitHub 是一個網站,您可以在其中儲存 Git 專案。 就像是共用和共同處理程序代碼與其他人的大型中樞。 它也有助於追蹤誰變更了哪些內容。

GitHub 與 Git 如何不同?

Git 是追蹤變更的工具,而 GitHub 是儲存專案並共同運作的地方。 GitHub 會使用 Git 執行其魔術。

GitHub 是否免費?

是,對於每個人都可以看到的專案。 但對於私人專案(只有您和小組),您可能需要支付費用。 它們提供具有額外功能的不同方案。

GitHub 中的提取要求為何?

提取要求就像要求將您的變更放入主要專案中一樣。 人員 可以在新增變更之前檢閱和討論這些變更。

GitHub 有多安全?

GitHub 會善加處理安全性。 他們會使用特殊程式代碼和規則,確保只有正確的人員可以存取和變更您的程序代碼。 您也可以新增額外的安全性層級,例如雙因素驗證,以取得更多安全性。