專為技術寫作人員提供的 7 條 Git 技巧
跟隨這個演示來了解我如何使用 Git 為 Foreman 編寫文檔。
作為 ATIX 的技術作家,我的任務包括為 Foreman 創建和維護存放在 github.com/theforeman/foreman-documentation 的文檔。Git 幫助我跟蹤內容的版本,並與開源社區進行協作。它是我存儲工作成果、共享和討論改進的重要工具。我主要使用的工具包括瀏覽器、用 OpenSSH 連接 Foreman 實例、用 Vim 編輯源文件,以及使用 Git 進行版本控制。
本文重點介紹在開始使用 Git 和為 Foreman 文檔做貢獻時經常遇到的挑戰。適用於中級 Git 用戶。
先決條件
- 你已在系統上安裝和配置了 Git。你至少需要設置用戶名和電子郵件地址。
- 你在 github.com 上擁有一個帳戶。GitHub 本身並不是一個開源項目,但它是許多開源 Git 存儲庫的託管站點(包括 Foreman 的文檔)。
- 你已將 foreman-documentation 存儲庫復刻到你自己的賬戶或組織(例如,
github.com/<My_User_Account>/foreman-documentation
,這裡<My_User_Account>
是你的 GitHub 用戶名)。有關更多信息,請參閱 Kedar Vijay Kulkarni 的 Kedar Vijay Kulkarni 的 Git 逐步指南。 - 你已將你的 SSH 公鑰添加到 GitHub。這是將你的更改推送到 GitHub 所必需的。有關更多信息,請參閱 Nicole C. Baratta 的《GitHub 簡單指引》。
對 Foreman 文檔做出貢獻
Foreman 是一個開源項目,依靠社區的貢獻而發展壯大。該項目歡迎所有人的參與,並且只有一些要求才能做出有意義的貢獻。這些要求和慣例在 README.md 和 CONTRIBUTING.md 文件中有詳細記錄。
以下是在處理 Foreman 文檔時最常見的一些任務。
我想開始貢獻 Foreman 文檔
1、從 github.com 克隆存儲庫:
$ git clone git@github.com:theforeman/foreman-documentation.git
$ cd foreman-documentation/
2、重命名遠程存儲庫:
$ git remote rename origin upstream
3、可選:確保你的本地主分支跟蹤 theforeman 組織的 foreman-documentation
存儲庫的 master
分支:
$ git status
這將自動將你置於默認分支(本例中為 master
)的最新提交上。
4、如果你的賬戶或組織中尚未有該存儲庫的 復刻 ,請創建一個。前往 github.com/theforeman/foreman-documentation 並點擊 「 復刻 」 按鈕。
5、將你的復刻添加到你的存儲庫中:
$ git remote add github git@github.com:<My_User_Account>/foreman-documentation.git
你的本地存儲庫現在有兩個遠程存儲庫:upstream
和 github
。
我想擴展 Foreman 文檔
對於簡單的更改,比如修正拼寫錯誤,你可以直接創建一個拉取請求(PR)。
1、創建一個分支,例如 fix_spelling
。git switch
命令用於切換當前所在的分支,-c
參數用於創建分支:
$ git switch -c fix_spelling
2、進行你的更改。
3、添加你的更改並進行提交:
$ git add guides/common/modules/abc.adoc
$ git commit -m "Fix spelling of existing"
良好的 Git 提交消息的重要性無需再強調。提交消息告訴貢獻者你做了哪些工作,因為它與代碼庫的其餘部分一起保存,所以它在查看代碼時起到歷史注釋的作用,幫助了解代碼的演化過程。有關優秀的 Git 提交消息的更多信息,請參閱由 cbeams 撰寫的 《創建完美的 Git 提交信息的 7 條規則》。
4、可選但建議的操作:查看並驗證與默認分支的差異。foreman-documentation
的默認分支稱為 master
,但其他項目可能有不同的命名(例如 main
、dev
或 devel
)。
$ git diff master
5、將分支推送到 GitHub。這將發布你的更改到你的代碼庫副本:
$ git push --set-upstream github fix_spelling
6、點擊終端中 Git 提供的鏈接來創建一個拉取請求(PR):
remote: Create a pull request for 'fix_spelling' on Github by visiting:
remote: https://github.com/_My_User_Account_/foreman-documentation/pull/new/fix_spelling
7、在解釋中說明社區為什麼應該接受你的更改。對於修正拼寫錯誤等簡單 PR,這並不是必需的,但對於重大更改則很重要。
我想將我的分支變基到 master
1、確保你的本地 master
分支跟蹤的是 github.com/theforeman/foreman-documentation 的 master
分支,而不是你自己命名空間下的 foreman-documentation
:
$ git switch master
此時應該顯示 Your branch is up to date with 'upstream/master'
,其中 upstream
是指向 github.com/theforeman/foreman-documentation
的遠程存儲庫的名稱。你可以通過運行 git remote -v
來查看遠程存儲庫設置情況。
2、從遠程獲取可能的更改。git fetch
命令會從遠程下載被跟蹤的分支,並且使用 --all
選項可以同時更新所有分支。在使用其他分支時這是必要的。--prune
選項會刪除對已不存在的分支的引用。
$ git fetch --all --prune
3、將可能的更改從 upstream/master
拉取到你的本地 master
分支。git pull
命令將跟蹤的分支上的提交複製到當前分支。這用於將你的本地 master
分支「更新」為遠程(在本例中為 GitHub)master
分支的最新狀態。
$ git pull
4、將你的分支 變基 到 master
。
$ git switch my_branch
$ git rebase -i master
我在 master 分支上意外地提交了代碼
1、創建一個分支來保存你的工作:
$ git switch -c my_feature
2、切換回 master
分支:
$ git switch master
3、回退 master
分支上的最後一次提交:
$ git reset --soft HEAD~1
4、切換回 my_feature
分支並繼續工作:
$ git switch my_feature
我想修改我的提交消息
1、如果你的分支只有一次提交,可以使用 git amend
來修改你的最後一次提交:
$ git commit --amend
這假設你沒有將其他文件添加到暫存區(即,沒有運行過 git add My_File
,並且沒有進行提交)。
2、使用 --force
選項將你的 「更改」 推送到 GitHub,因為 Git 提交消息是你現有提交的一部分,所以你正在更改分支上的歷史記錄:
$ git push --force
我想重新整理單個分支上的多個更改
1、可選但強烈推薦:從 GitHub 獲取更改。
$ git switch master
$ git fetch
$ git pull
這確保你將其他更改按照它們被合併到 master
中的順序直接合併到你的分支中。
2、若要重新整理你的工作,請對你的分支進行變基並根據需要進行更改。對於將分支變基到 master
,這意味著你需要更改你的分支上第一個提交的父提交:
$ git rebase --interactive master
使用你喜歡的編輯器打開變基交互界面,將第一個單詞 pick
替換為你要修改的提交。
- 使用
e
來對你的提交進行實際更改。這會中斷你的變基操作! - 使用
f
將一個提交與其父提交合併。 - 使用
d
完全刪除一個提交。 - 移動行以改變你更改的順序。
成功進行變基後,你自己的提交將位於 master
上最後一個提交的頂部。
我想從其他分支複製一個提交
1、從穩定分支(例如名為 3.3
的分支)獲取提交的 ID,請使用 -n
選項限制提交數量:
$ git log -n 5 3.3
2、通過挑選提交來複制更改到你的分支。-x
選項將提交的 ID 添加到你的提交消息中。這僅建議在從穩定分支挑選提交時使用:
$ git switch My_Branch
$ git cherry-pick -x Commit_ID
更多技巧
在 ATIX,我們運行一個 GitLab 實例,用於內部共享代碼、協作以及自動化測試和構建。對於圍繞 Foreman 生態系統的開源社區,我們依賴於 GitHub。
我建議你始終將名為 origin
的遠程指向你的內部的版本控制系統。這樣做可以防止在純粹憑記憶進行 git push
時向外部服務泄露信息。
此外,我建議使用固定的命名方案來命名遠程。我總是將指向自己的 GitLab 實例的遠程命名為 origin
,將指向開源項目的遠程命名為 upstream
,將指向我在 Github 上的復刻的遠程命名為 github
。
對於 foreman-documentation
,該存儲庫具有相對較平的歷史記錄。當處理更複雜結構時,我傾向於以非常可視化的方式思考 Git 存儲庫,其中節點(提交)指向線上的節點(分支),這些分支可以交織在一起。圖形化工具如 gitk
或 Git Cola 可以幫助可視化你的 Git 歷史記錄。一旦你完全掌握了 Git 的工作原理,如果你更喜歡命令行,可以使用別名。
在進行具有大量預期合併衝突的大型變基之前,我建議創建一個「備份」分支,以便你可以快速查看差異。請注意,要永久刪除提交是相當困難的,因此在進行重大更改之前,請在本地 Git 存儲庫中進行測試。
Git 對技術文檔編寫者的幫助
Git 對技術文檔編寫者來說是一個巨大的幫助。不僅可以使用 Git 對文檔進行版本控制,還可以與他人積極地進行協作。
(題圖:MJ/1fb1dd43-e460-4e76-9ff6-b6ef76570f7e)
via: https://opensource.com/article/22/11/git-tips-technical-writers
作者:Maximilian Kolb 選題:lkxed 譯者:ChatGPT 校對:wxy
本文轉載來自 Linux 中國: https://github.com/Linux-CN/archive