🌍 English ∙ Español ∙ Русский ∙ 繁體中文 ∙ 簡體中文 ∙ 한국어 ∙ Tiếng Việt ∙ Français ∙ 日本語
- 英文原版 README
- 翻譯可能存在錯誤或不標準的地方,歡迎大家指正和修改,謝謝!
這是一篇給太空人(這裡就是指使用 Git 的程式設計師們)的指南,用來指導問題出現後的應對之法。
飛行規則(Flight Rules)是記錄在手冊上的來之不易的一系列知識,記錄了某個事情發生的原因,以及怎樣一步一步的進行處理。本質上,它們是特定場景的非常詳細的標準處理流程。[...]
自 20 世紀 60 年代初以來,NASA 一直在捕捉(capturing)失誤、災難和解決方案。當時水星時代(Mercury-era)的地面小組首先開始將「經驗教訓」收集到一個綱要(compendium)中,該綱現在已經有上千個問題情景,從發動機故障、到破損的艙口把手、再到計算機故障,以及它們對應的解決方案。
——Chris Hadfield,《一個太空人的生活指南》(An Astronaut's Guide to Life)
為了清楚的表述,這篇文件裡的所有例子使用了自訂的 bash 提示,以便指示目前分支和是否有暫存的變化(changes)。分支名用小括號括起來,分支名後面跟的 *
表示暫存的變化(changes)。
Table of Contents generated with DocToc
- 編輯提交(editting commits)
- 暫存(staging)
- 未暫存(unstaged)的變化
- 分支(branches)
- 變基(rebase)與合併(merge)
- 儲藏(stash)
- 雜項
- 追蹤檔案(tracking files)
- 組態(configuration)
- 我不知道我做錯了什麼
- 其他資源
如果你用 git commit -a
提交了一次變化(changes),而你又不確定到底這次提交了哪些內容,你可以用以下命令顯示目前 HEAD
上的最近一次的提交(commit):
(main)$ git show
或者
$ git log -n1 -p
如果你的提交訊息(commit message)寫錯了,且這次提交(commit)還沒有推送(push),你可以透過下面的方法來修改提交訊息(commit message):
$ git commit --amend --only
這會使用你的預設編輯器來完成。你也可以只使用一個命令:
$ git commit --amend --only -m 'xxxxxxx'
如果你已經推送(push)了這次提交(commit),你可以修改這次提交(commit)然後強制推送(force push),但是不推薦這麼做。
如果這只是單個提交(commit),修改它:
$ git commit --amend --author "New Authorname <[email protected]>"
如果你需要修改所有歷史,參考 git filter-branch
的手冊。
通過下面的方法,從一個提交(commit)裡移除一個文件:
$ git checkout HEAD^ myfile
$ git add -A
$ git commit --amend
這非常有用,當你有一個開放的補丁(open patch),你往上面提交了一個不必要的文件,你需要強制推送(force push)去更新這個遠程補丁。
如果你需要刪除推送了的提交(pushed commits),你可以使用以下方法。但是,這將不可逆的改變你的歷史,也會搞亂那些已經從該倉庫拉取(pulled)了的人的歷史。簡而言之,如果你不是很確定,千萬不要這麼做。
$ git reset HEAD^ --hard
$ git push -f [remote] [branch]
如果你還沒有推送到遠端,重設(reset)到你最後一次提交前的狀態就可以了(同時保存暫存的變化):
(my-branch)$ git reset --soft HEAD^
這只能在推送之前使用。如果你已經推送了,唯一安全的做法是 git revert SHAofBadCommit
,那會創建一個新的提交(commit)來撤消前一個提交的所有變化(changes);或者,如果這個分支是 rebase-safe 的(例如:其他開發者不會從這個分支拉取),只需要使用 git push -f
;參見上一節。
同樣,除非必須,否則不要這麼做。
$ git rebase --onto SHA1_OF_BAD_COMMIT^ SHA1_OF_BAD_COMMIT
$ git push -f [remote] [branch]
或者使用互動式變基(interactive rebase) 刪除那些你想要刪除的提交(commit)所對應的行。
To https://github.com/yourusername/repo.git
! [rejected] mybranch -> mybranch (non-fast-forward)
error: failed to push some refs to 'https://github.com/tanay1337/webmaker.org.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Integrate the remote changes (e.g.
hint: 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.
注意,變基(rebasing)和修正(amending)會用一個新的提交(commit)取代舊的,所以如果舊的提交已經推送到遠端上了,那你必須強制推送(force push)。注意:總是確保你指明一個分支!
(my-branch)$ git push origin mybranch -f
一般來說,要避免強制推送。最好是創建和推送一個新的提交(commit),而不是強推一個修正後的提交。後者會使在該分支或該分支的子分支上工作的開發者,在源歷史中產生衝突。
如果你意外地做了 git reset --hard
,你通常能找回你的提交(commit),因為 Git 對每件事都會有日誌,且都會保存幾天。
(main)$ git reflog
你將會看到一個你過去提交(commit)的列表,和一個重設的提交。選擇你想要回到的提交(commit)的 SHA,再重設一次:
(main)$ git reset --hard SHA1234
(my-branch*)$ git commit --amend
一般來說,如果你想暫存一個文件的一部分,你可以使用以下命令來開啟互動式介面,並使用 s
選項來選擇想要的行。
$ git add --patch filename.x # 或 `-p`。
然而,當這個檔案是新的,則需改用以下命令:
$ git add -N filename.x
然後,你需要用 e
選項來選擇需要添加的行,執行 git diff --cached
將會顯示哪些行暫存了、哪些行只是保存在本地了。
git add
會把整個文件加入到一個提交。git add -p
則允許你互動式地選擇想要提交的部分。
多數情況下,你應該將所有的內容變為未暫存,然後再加入(add)你想要的內容提交(commit)。 但如果你就是想這麼做,你可以創建一個臨時的提交來儲存你已暫存的內容,然後加入未暫存的內容並儲藏(stash)。最後,重設(reset)最後一個提交將原本暫存的內容變為未暫存,最後彈出儲藏(pop stash)。
$ git commit -m "WIP" # 將之前已暫存的內容提交。
$ git add . # 加入未暫存的內容。
$ git stash # 儲藏剛剛加入的內容。
$ git reset HEAD^ # 重設到父提交。
$ git stash pop --index 0 # 彈出儲藏。
註一:這裡使用 pop
僅僅是因為想盡可能保持冪等。
註二:假如不加上 --index
,會把暫存的文件標記為未暫存。這裡解釋得比較清楚。(其大意是說,這是一個較為底層的問題,儲藏時會創建兩個提交,一個記錄 index 狀態、暫存的內容等,另一個紀錄 worktree 和其他的一些東西,如果你不在 apply 時加 index,Git 會把兩個一起銷毀,所以暫存區(stage)裡就空了)。
$ git checkout -b my-branch
$ git stash
$ git checkout my-branch
$ git stash pop
如果你只是想重設源(origin)和你本地(local)之間的一些提交(commit),你可以:
# one commit
(my-branch)$ git reset --hard HEAD^
# two commits
(my-branch)$ git reset --hard HEAD^^
# four commits
(my-branch)$ git reset --hard HEAD~4
# or
(main)$ git checkout -f
如果要重設某個特定檔案,可以用檔案名做為引數:
$ git reset filename
如果你想丟棄工作拷貝中的一部分內容,而不是全部。
簽出(checkout)不需要的內容,保留需要的。
$ git checkout -p
# Answer y to all of the snippets you want to drop
另外一個方法是使用儲藏(stash),儲藏所有要保留的變化,重設工作拷貝,然後把儲藏彈出。
$ git stash -p
# Select all of the snippets you want to save
$ git reset --hard
$ git stash pop
或者,儲藏你不需要的部分,然後丟棄儲藏(drop stash)。
$ git stash -p
# Select all of the snippets you don't want to save
$ git stash drop
這是另外一種可以使用 git reflog
情況,找到在這次錯誤拉取(pull)之前 HEAD 的指向。
(main)$ git reflog
ab7555f HEAD@{0}: pull origin wrong-branch: Fast-forward
c5bc55a HEAD@{1}: checkout: checkout message goes here
然後,重設分支到所需的提交:
$ git reset --hard c5bc55a
完成。
首先,確認你沒有推送(push)你的內容到遠端。
git status
會顯示本地領先(ahead)源(origin)多少個提交:
(my-branch)$ git status
# On branch my-branch
# Your branch is ahead of 'origin/my-branch' by 2 commits.
# (use "git push" to publish your local commits)
#
一種方法是:
(my-branch)$ git reset --hard origin/my-branch
在 main
下創建一個新分支:
(main)$ git branch my-branch
把 main
重設到前一個提交:
(main)$ git reset --hard HEAD^
HEAD^
是 HEAD^1
的縮寫,你可以指定數字來進一步重設。或者,如果你不想使用 HEAD^
,你可以指定一個提交(commit)的雜湊值(hash)(可以使用 git log
查看),如 git reset --hard a13b85e
。
簽出(checkout)到剛才新建的分支繼續工作:
(main)$ git checkout my-branch
假設你正在做一個原型方案(原文為 working spike),有成百上千的內容。當你提交到一個分支,儲存工作內容:
(solution)$ git add -A && git commit -m "Adding all changes from this spike into one big commit."
當你想要把它放到一個分支裡(假設是 develop
),你希望保持整個檔案的完整,並將大的提交分割成數個小的。
假設這裡有:
- 分支
solution
,擁有原型方案,領先develop
分支。 - 分支
develop
,應用原型方案的一些內容。
可以將內容放到那個分支中:
(develop)$ git checkout solution -- file1.txt
(develop)$ git status
# On branch develop
# Your branch is up-to-date with 'origin/develop'.
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
#
# modified: file1.txt
然後,普通地提交。
註:Spike solutions are made to analyze or solve the problem. These solutions are used for estimation and discarded once everyone gets clear visualization of the problem. ~ Wikipedia.
假設在 main
分支,執行 git log
的結果如下:
(main)$ git log
commit e3851e817c451cc36f2e6f3049db528415e3c114
Author: Alex Lee <[email protected]>
Date: Tue Jul 22 15:39:27 2014 -0400
Bug #21 - Added CSRF protection
commit 5ea51731d150f7ddc4a365437931cd8be3bf3131
Author: Alex Lee <[email protected]>
Date: Tue Jul 22 15:39:12 2014 -0400
Bug #14 - Fixed spacing on title
commit a13b85e984171c6e2a1729bb061994525f626d14
Author: Aki Rose <[email protected]>
Date: Tue Jul 21 01:12:48 2014 -0400
First commit
要把 e3851e8
和 5ea5173
分別移到新的分支,首先,要把 main
分支重設到正確的提交(a13b85e
):
(main)$ git reset --hard a13b85e
HEAD is now at a13b85e
新增一個分支:
(main)$ git checkout -b 21
接著,然後挑揀(cherry-pick)提交到正確的分支上。這意味著我們將直接在 HEAD 上面應用(apply)這個提交。
(21)$ git cherry-pick e3851e8
這可能會造成衝突(conflict),參見〈互動式變基・衝突〉來解決衝突。
同樣地,為 5ea5173
也創建一個分支,並把提交挑揀到其上:
(main)$ git checkout -b 14
(14)$ git cherry-pick 5ea5173
比方說,在 GitHub 中,合併(merge)了拉取請求(pull request)後,就可以刪除掉分支。如果不準備繼續在這個分支上工作,刪除這個分支會使工作拷貝(working copy)更乾淨。
$ git fetch -p
如果你定期推送(push)到遠端(remote),多數情況下應該是安全的,但有時可能刪除了還沒推送的分支。
為了模擬這種情況,首先,創建一個分支和一個檔案:
(main)$ git checkout -b my-branch
(my-branch)$ touch foo.txt
(my-branch)$ ls
README.md foo.txt
加入變化並提交:
(my-branch)$ git add .
(my-branch)$ git commit -m 'foo.txt added'
(my-branch)$ git log
commit 4e3cd85a670ced7cc17a2b5d8d3d809ac88d5012
Author: siemiatj <[email protected]>
Date: Wed Jul 30 00:34:10 2014 +0200
foo.txt added
commit 69204cdf0acbab201619d95ad8295928e7f411d5
Author: Kate Hudson <[email protected]>
Date: Tue Jul 29 13:14:46 2014 -0400
Fixes #6: Force pushing after amending commits
現在,切回 main
分支,並「不小心」刪除了 my-branch
:
(my-branch)$ git checkout main
Switched to branch 'main'
Your branch is up-to-date with 'origin/main'.
(main)$ git branch -D my-branch
Deleted branch my-branch (was 4e3cd85).
(main)$ echo oh noes, deleted my branch!
oh noes, deleted my branch!
你應該想起了 reflog
,它記錄了所有動作。
(main)$ git reflog
69204cd HEAD@{0}: checkout: moving from my-branch to main
4e3cd85 HEAD@{1}: commit: foo.txt added
69204cd HEAD@{2}: checkout: moving from main to my-branch
如你所見,其中包含了刪除分支的提交的雜湊值(hash)。可以藉此把提交找回來:
(main)$ git checkout -b my-branch-help
Switched to a new branch 'my-branch-help'
(my-branch-help)$ git reset --hard 4e3cd85
HEAD is now at 4e3cd85 foo.txt added
(my-branch-help)$ ls
README.md foo.txt
看!我們把遺失的檔案找回來了。Git 的 reflog
在變基(rebase)出錯時也同樣有用。
刪除一個遠端分支:
(main)$ git push origin --delete my-branch
或:
(main)$ git push origin :my-branch
刪除一個本地分支:
(main)$ git branch -D my-branch
首先,從遠端獲取(fetch)所有分支:
(main)$ git fetch --all
假設你想要從遠端的 daves
分支簽出到本地的 daves
:
(main)$ git checkout --track origin/daves
Branch daves set up to track remote branch daves from origin.
Switched to a new branch 'daves'
(--track
是 git checkout -b [branch] [remotename]/[branch]
的縮寫。)
這樣就有 daves
的本地拷貝了。
你可能對一個錯誤的分支做了變基或合併,或者無法完成變基或合併。Git 在進行危險操作時,會將原本的 HEAD
存成 ORIG_HEAD
,因此可以很容易的恢復到之前的狀態。
(my-branch)$ git reset --hard ORIG_HEAD
不幸的是,如果你想把變基的結果反映在遠端分支上,你必須強制推送(force push)。因為你改變了歷史,遠端不會接受使用快進(fast-forward),而必須強制推送。這就是許多人使用合併工作流程、而不是變基工作流程的主要原因之一,開發者的強制推送會使大團隊陷入麻煩。
一種安全的方式是,不要推送到遠端:
(main)$ git checkout my-branch
(my-branch)$ git rebase -i main
(my-branch)$ git checkout main
(main)$ git merge --ff-only my-branch
假設你的工作分支將對 main
分支做拉取請求(pull request)。
最簡單的情況下,不會關心提交的時間戳(timestamp),只想將所有的提交組合成一個單獨的提交,你可以重設(reset)和重新提交(recommit)。確保 main
是最新的,且你的變化都已經提交,然後:
(my-branch)$ git reset --soft main
(my-branch)$ git commit -am "New awesome feature"
如果你想保留更多控制、保留時間戳,你需要互動式變基(interactive rebase):
(my-branch)$ git rebase -i main
如果沒有相對於其他分支,將不得不相對於 HEAD
變基。例如,要組合最近的兩次提交,需相對於 HEAD~2
變基,組合最近三次提交,則相對於 HEAD~3
,以此類推。
(main)$ git rebase -i HEAD~2
在執行了互動式變基的命令(interactive rebase command)後,你會在編輯器裡看到類似以下的內容:
pick a9c8a1d Some refactoring
pick 01b2fd8 New awesome feature
pick b729ad5 fixup
pick e3851e8 another fix
# Rebase 8074d12..b729ad5 onto 8074d12
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out
(以 #
開頭的行是註解,不影響變基。)
你可以以註解中提到的命令替換 pick
,也可以刪除一行來刪除對應的提交。例如,如果要保留最舊(first)的提交,並將其他組合成第二個提交,應該將第二個提交之後所有提交的命令改為 f
:
pick a9c8a1d Some refactoring
pick 01b2fd8 New awesome feature
f b729ad5 fixup
f e3851e8 another fix
如果要組合並重新命名這個提交,應該在第二個提交加上 r
,或使用 s
取代 f
:
pick a9c8a1d Some refactoring
pick 01b2fd8 New awesome feature
s b729ad5 fixup
s e3851e8 another fix
你可以在接著彈出的文字提示中重新命名那個提交:
Newer, awesomer features
# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# rebase in progress; onto 8074d12
# You are currently editing a commit while rebasing branch 'main' on '8074d12'.
#
# Changes to be committed:
# modified: README.md
#
應該會看到如下的成功訊息:
(main)$ Successfully rebased and updated refs/heads/main.
--no-commit
選項會合併但不會自動提交,給使用者在提交前檢查和修改的機會。--no-ff
會留下功能分支(feature branch)存在過的證據,保持歷史一致。
(main)$ git merge --no-ff --no-commit my-branch
(main)$ git merge --squash my-branch
假設在推送到上遊前,你有幾個正在進行的工作提交,這時候不希望把已推送的提交也組合進來,因為其他人可能已經有提交引用它們了。
(main)$ git rebase -i @{u}
這會進行一次互動式變基(interactive rebase),只會列出還沒推送的提交。對這些提交重新排序或做 squash、fixup 都是安全的。
要檢查一個分支上的所有提交是否都已經合併進了其它分支,應該在這些分支的 HEAD
(或任何提交)之間檢查差異:
(main)$ git log --graph --left-right --cherry-pick --oneline HEAD...feature/120-on-scroll
這會顯示一個分支有而另一個分支沒有的提交,和分支之間不共享的提交的列表。
另一個方法是:
(main)$ git log main ^feature/120-on-scroll --no-merges
如果你看到:
noop
表示變基的分支和目前分支在同一個提交,或領先(ahead)目前分支。你可以嘗試:
- 確保
main
分支沒有問題 - 對
HEAD~2
或更早的提交變基
如果不能成功的完成變基,你可能必須要解決衝突(resolve conflict)。
首先用 git status
檢查哪些檔案有衝突:
(my-branch)$ git status
On branch my-branch
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)
modified: README.md
在這個例子中,README.md
有衝突。打開衝突的檔案會看到類似下面的內容:
<<<<<<< HEAD
some code
=========
some code
>>>>>>> new-commit
你必須解決新提交的內容和 HEAD
中的內容的衝突。
有時候衝突非常複雜,你可以使用可視化差異編輯器(visual diff editor):
(main*)$ git mergetool -t opendiff
解決所有衝突後,加入變化了的檔案,然後用 git rebase --continue
繼續變基:
(my-branch)$ git add README.md
(my-branch)$ git rebase --continue
如果在解決所有衝突過後,得到了與提交前一樣的結果,可以使用 git rebase --skip
。
如果想放棄變基,回到之前的狀態,可以在任何時候用:
(my-branch)$ git rebase --abort
儲藏工作目錄下所有變化:
$ git stash
可以使用 -u
選項排除一些檔案:
$ git stash -u
儲藏一個檔案:
$ git stash push working-directory-path/filename.ext
儲藏多個檔案:
$ git stash push working-directory-path/filename1.ext working-directory-path/filename2.ext
$ git stash save <message>
或
$ git stash push -m <message>
如此可以在使用 stash list
時看到訊息。
可以先列出擁有的儲藏:
$ git stash list
然後,將以下命令的 n
替換成儲藏在堆疊中的位置(最上方為 0
),應用指定儲藏:
$ git stash apply "stash@{n}"
除此之外,也可以使用時間標記(假如你能記住的話),如:
$ git stash apply "stash@{2.hours.ago}"
你需要先手動創建一個儲藏提交,然後使用 git stash store
。
$ git stash create
$ git stash store -m "commit-message" CREATED_SHA1
$ git clone --recursive git://github.com/foo/bar.git
如果已經複製了:
$ git submodule update --init --recursive
$ git tag -d <tag_name>
$ git push <remote> :refs/tags/<tag_name>
如果想恢復一個已刪除標籤,首先,找到無法觸及的標籤(unreachable tag):
$ git fsck --unreachable | grep tag
記下這個標籤的雜湊值,然後用 Git 的 update-ref
:
$ git update-ref refs/tags/<tag_name> <hash>
如果有人在 GitHub 上向你提出了拉取請求(pull request),但他接著刪除了他的分叉(fork),你無法複製他的提交或使用 git am
。在這種情況下,最好手動的查看他們的提交,把它們拷貝到一個本地新分支,然後提交。
最後,再修改作者,參見〈變更作者〉。然後,應用變化,再發起一個新的拉取請求。
(main)$ git mv --force myfile MyFile
(main)$ git rm --cached log.txt
在 OS X 和 Linux 下,Git 的組態檔案儲存在 ~/.gitconfig
。可以在 [alias]
部分設定一些快捷別名(以及容易拼錯的),如:
[alias]
a = add
amend = commit --amend
c = commit
ca = commit --amend
ci = commit -a
co = checkout
d = diff
dc = diff --changed
ds = diff --staged
f = fetch
loll = log --graph --decorate --pretty=oneline --abbrev-commit
m = merge
one = log --pretty=oneline
outstanding = rebase -i @{u}
s = status
unpushed = log @{u}
wc = whatchanged
wip = rebase -i @{u}
zap = fetch -p
假設有一個倉庫需要授權,這時你可以快取使用者名稱和密碼,而不用每次推送和拉取時都輸入一次:
$ git config --global credential.helper cache
# Set Git to use the credential memory cache.
$ git config --global credential.helper 'cache --timeout=3600'
# Set the cache to timeout after 1 hour (setting is in seconds).
如果你把事情搞砸了:你錯誤地重設、合併,或強制推送後找不到自己的提交了,抑或你做得很好,但你想回到以前的某個狀態。
這就是 git reflog
的目的,reflog
記錄對分支頂端(the tip of a branch)的任何改變,即使沒有任何分支或標籤參考那個頂端。基本上,只要 HEAD
改變,reflog
就會記錄下來。遺憾的是,這只對本地分支起作用,且它只追蹤動作(例如,不會追蹤一個沒被記錄的檔案的任何改變)。
(main)$ git reflog
0a2e358 HEAD@{0}: reset: moving to HEAD~2
0254ea7 HEAD@{1}: checkout: moving from 2.2 to main
c10f740 HEAD@{2}: checkout: moving from main to 2.2
上面的 reflog
顯示了曾經從 main
分支簽出到 2.2
分支,然後再簽出回去,還有硬重設到一個較舊的提交。最新的動作出現在最上面,並以 HEAD@{0}
標示。
如果你不小心回移(move back)了提交,reflog
會包含回移前 main
參考的提交(在這個例子中是 0254ea7
)。只要硬重設就能恢復到之前的狀態,這提供了歷史不小心被變更時的安全網。
$ git reset --hard 0254ea7
摘自這裡。
- Pro Git——Scott Chacon 的傑出書籍
- Git Internals——Scott Chacon 的另一本傑出書籍
- Learn Git branching——一個基於網頁的互動式分支、合併、變基教學
- Getting solid at Git rebase vs. merge
- git-workflow——Aaron Meurer 的怎麼使用 Git 開源貢獻
- GitHub as a workflow——GitHub 作為工作流程的趣事,特別是空拉取請求
- firstaidgit.io——一個可搜尋的 Git 常見問題集
- git-extra-commands——一堆有用的額外 Git 腳本
- git-extras——Git 工具集,倉庫概要、repl、變更記錄、提交百分比和更多
- git-fire——git-fire 是一個 Git 插件,用於在緊急情況下幫助加入目前所有檔案、提交、推送到一個新分支(防止合併衝突)。
- git-tips——Git 小撇步
- git-town——通用、高級 Git 工作流程支援! http://www.git-town.com