章節 ▾ 第二版

8.4 定製 Git - 一個 Git 強制策略示例

一個 Git 強制策略示例

在本節中，你將運用所學知識建立一個 Git 工作流，該工作流將檢查自定義提交訊息格式，並且只允許特定使用者修改專案中的特定子目錄。你將構建客戶端指令碼來幫助開發者瞭解他們的推送是否會被拒絕，以及伺服器指令碼來實際強制執行這些策略。

我們將展示的指令碼是用 Ruby 編寫的；部分原因是我們的思維慣性，但也因為 Ruby 即使你不一定會寫，也易於閱讀。然而，任何語言都可以——Git 分發的所有示例鉤子指令碼都是用 Perl 或 Bash 編寫的，因此你也可以透過檢視這些示例來了解這些語言的許多鉤子示例。

伺服器端鉤子

所有伺服器端工作都將放入你 hooks 目錄中的 update 檔案。update 鉤子在每次推送分支時執行一次，並接受三個引數

  • 正在推送到的引用名稱

  • 該分支之前的舊版本

  • 正在推送的新版本

如果推送是透過 SSH 執行的，你還可以訪問進行推送的使用者。如果你允許所有人透過公鑰認證連線到單個使用者（例如“git”），你可能需要給該使用者一個 shell 封裝器，根據公鑰確定正在連線的使用者，並相應地設定一個環境變數。這裡我們假設連線使用者在 $USER 環境變數中，所以你的 update 指令碼首先收集所有你需要的資訊

#!/usr/bin/env ruby

$refname = ARGV[0]
$oldrev  = ARGV[1]
$newrev  = ARGV[2]
$user    = ENV['USER']

puts "Enforcing Policies..."
puts "(#{$refname}) (#{$oldrev[0,6]}) (#{$newrev[0,6]})"

是的，這些是全域性變數。不要評判——這樣演示更容易。

強制執行特定的提交訊息格式

你的第一個挑戰是強制每個提交訊息都遵循特定的格式。為了設定一個目標，假設每個訊息都必須包含一個看起來像“ref: 1234”的字串，因為你希望每個提交都連結到你的工單系統中的一個工作項。你必須檢查正在推送的每個提交，檢視該字串是否存在於提交訊息中，如果該字串在任何提交中都不存在，則以非零狀態退出，以便拒絕推送。

你可以透過獲取 $newrev 和 $oldrev 的值並將它們傳遞給一個名為 git rev-list 的 Git 底層命令來獲取所有正在推送的提交的 SHA-1 值列表。這基本上就是 git log 命令，但預設情況下它只打印 SHA-1 值，沒有其他資訊。因此，要獲取一個提交 SHA-1 和另一個提交 SHA-1 之間引入的所有提交 SHA-1 的列表，你可以執行類似這樣的命令

$ git rev-list 538c33..d14fc7
d14fc7c847ab946ec39590d87783c69b031bdfb7
9f585da4401b0a3999e84113824d15245c13f0be
234071a1be950e2a8d078e6141f5cd20c1e61ad3
dfa04c9ef3d5197182f13fb5b9b1fb7717d2222a
17716ec0f1ff5c77eff40b7fe912f9f6cfd0e475

你可以獲取該輸出，迴圈遍歷每個提交 SHA-1，獲取其訊息，並針對查詢模式的正則表示式測試該訊息。

你必須弄清楚如何從這些提交中獲取提交訊息進行測試。要獲取原始提交資料，你可以使用另一個底層命令 git cat-file。我們將在 Git 內部原理中詳細介紹所有這些底層命令；但現在，該命令會給你以下內容

$ git cat-file commit ca82a6
tree cfda3bf379e4f8dba8717dee55aab78aef7f4daf
parent 085bb3bcb608e1e8451d4b2432f8ecbe6306e7e7
author Scott Chacon <schacon@gmail.com> 1205815931 -0700
committer Scott Chacon <schacon@gmail.com> 1240030591 -0700

Change the version number

從擁有 SHA-1 值的提交中獲取提交訊息的一個簡單方法是找到第一個空行，然後獲取其後的所有內容。你可以在 Unix 系統上使用 sed 命令來完成

$ git cat-file commit ca82a6 | sed '1,/^$/d'
Change the version number

你可以使用該命令獲取每個嘗試推送的提交的提交訊息，如果發現任何不匹配的內容則退出。要退出指令碼並拒絕推送，請以非零狀態退出。整個方法如下所示

$regex = /\[ref: (\d+)\]/

# enforced custom commit message format
def check_message_format
  missed_revs = `git rev-list #{$oldrev}..#{$newrev}`.split("\n")
  missed_revs.each do |rev|
    message = `git cat-file commit #{rev} | sed '1,/^$/d'`
    if !$regex.match(message)
      puts "[POLICY] Your message is not formatted correctly"
      exit 1
    end
  end
end
check_message_format

將其放入你的 update 指令碼中，將拒絕包含不符合你規則的訊息的提交的更新。

強制執行基於使用者的 ACL 系統

假設你想新增一個機制，使用訪問控制列表（ACL）來指定哪些使用者可以向專案的哪些部分推送更改。有些人擁有完全訪問許可權，而另一些人只能向某些子目錄或特定檔案推送更改。為了強制執行此操作，你將把這些規則寫入一個名為 acl 的檔案，該檔案位於伺服器上的裸 Git 倉庫中。你將讓 update 鉤子檢視這些規則，檢視所有正在推送的提交中引入了哪些檔案，並確定執行推送的使用者是否有權更新所有這些檔案。

你要做的第一件事是編寫你的 ACL。這裡你將使用一種非常類似於 CVS ACL 機制的格式：它使用一系列行，其中第一個欄位是 avail 或 unavail，下一個欄位是逗號分隔的規則適用的使用者列表，最後一個欄位是規則適用的路徑（空白表示開放訪問）。所有這些欄位都由豎線 (|) 字元分隔。

在這種情況下，你有一些管理員，一些擁有 doc 目錄訪問許可權的文件編寫者，以及一個只擁有 lib 和 tests 目錄訪問許可權的開發者，你的 ACL 檔案看起來像這樣

avail|nickh,pjhyett,defunkt,tpw
avail|usinclair,cdickens,ebronte|doc
avail|schacon|lib
avail|schacon|tests

你首先將這些資料讀入一個你可以使用的結構中。在這種情況下，為了簡化示例，你將只強制執行 avail 指令。這是一個方法，它為你提供一個關聯陣列，其中鍵是使用者名稱，值是使用者擁有寫入許可權的路徑陣列

def get_acl_access_data(acl_file)
  # read in ACL data
  acl_file = File.read(acl_file).split("\n").reject { |line| line == '' }
  access = {}
  acl_file.each do |line|
    avail, users, path = line.split('|')
    next unless avail == 'avail'
    users.split(',').each do |user|
      access[user] ||= []
      access[user] << path
    end
  end
  access
end

在你之前檢視的 ACL 檔案上，這個 get_acl_access_data 方法返回的資料結構如下所示

{"defunkt"=>[nil],
 "tpw"=>[nil],
 "nickh"=>[nil],
 "pjhyett"=>[nil],
 "schacon"=>["lib", "tests"],
 "cdickens"=>["doc"],
 "usinclair"=>["doc"],
 "ebronte"=>["doc"]}

現在你已經理清了許可權，你需要確定正在推送的提交修改了哪些路徑，這樣你就可以確保進行推送的使用者有權訪問所有這些路徑。

你可以使用 git log 命令的 --name-only 選項（在 Git 基礎中簡要提及）非常容易地檢視單個提交中修改了哪些檔案

$ git log -1 --name-only --pretty=format:'' 9f585d

README
lib/test.rb

如果你使用從 get_acl_access_data 方法返回的 ACL 結構，並將其與每個提交中列出的檔案進行檢查，你可以確定使用者是否有權推送所有提交

# only allows certain users to modify certain subdirectories in a project
def check_directory_perms
  access = get_acl_access_data('acl')

  # see if anyone is trying to push something they can't
  new_commits = `git rev-list #{$oldrev}..#{$newrev}`.split("\n")
  new_commits.each do |rev|
    files_modified = `git log -1 --name-only --pretty=format:'' #{rev}`.split("\n")
    files_modified.each do |path|
      next if path.size == 0
      has_file_access = false
      access[$user].each do |access_path|
        if !access_path  # user has access to everything
           || (path.start_with? access_path) # access to this path
          has_file_access = true
        end
      end
      if !has_file_access
        puts "[POLICY] You do not have access to push to #{path}"
        exit 1
      end
    end
  end
end

check_directory_perms

你使用 git rev-list 獲取正在推送到伺服器的新提交列表。然後，對於每個提交，你找出哪些檔案被修改，並確保執行推送的使用者有權訪問所有被修改的路徑。

現在你的使用者無法推送帶有格式錯誤訊息的提交，也無法推送修改了指定路徑之外檔案的提交。

測試

如果你執行 chmod u+x .git/hooks/update（這是你本應將所有這些程式碼放入的檔案），然後嘗試推送一個不符合規範訊息的提交，你將得到類似這樣的結果

$ git push -f origin master
Counting objects: 5, done.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 323 bytes, done.
Total 3 (delta 1), reused 0 (delta 0)
Unpacking objects: 100% (3/3), done.
Enforcing Policies...
(refs/heads/master) (8338c5) (c5b616)
[POLICY] Your message is not formatted correctly
error: hooks/update exited with error code 1
error: hook declined to update refs/heads/master
To git@gitserver:project.git
 ! [remote rejected] master -> master (hook declined)
error: failed to push some refs to 'git@gitserver:project.git'

這裡有幾個有趣的地方。首先，你會在鉤子開始執行時看到這個。

Enforcing Policies...
(refs/heads/master) (fb8c72) (c56860)

請記住，你是在 update 指令碼的最開始打印出這些內容的。你的腳本回顯到 stdout 的任何內容都將傳輸到客戶端。

接下來你會注意到錯誤訊息。

[POLICY] Your message is not formatted correctly
error: hooks/update exited with error code 1
error: hook declined to update refs/heads/master

第一行是你打印出來的，另外兩行是 Git 告訴你 update 指令碼以非零狀態退出，這就是它拒絕你的推送的原因。最後，你會看到這個

To git@gitserver:project.git
 ! [remote rejected] master -> master (hook declined)
error: failed to push some refs to 'git@gitserver:project.git'

你將看到你的鉤子拒絕的每個引用的“遠端拒絕”訊息，它會告訴你被拒絕的具體原因是鉤子失敗。

此外，如果有人嘗試編輯他們無權訪問的檔案並推送包含該檔案的提交，他們會看到類似的內容。例如，如果一個文件作者嘗試推送修改 lib 目錄中某些內容的提交，他們會看到

[POLICY] You do not have access to push to lib/test.rb

從現在開始，只要 update 指令碼存在且可執行，你的倉庫中就不會有不包含你指定模式的提交訊息，並且你的使用者將處於沙盒環境中。

客戶端鉤子

這種方法的缺點是當用戶的提交推送被拒絕時，不可避免地會導致抱怨。他們精心完成的工作在最後一刻被拒絕可能會非常令人沮喪和困惑；此外，他們將不得不編輯他們的歷史記錄來糾正它，這對於膽小的人來說並非易事。

解決這個困境的方法是提供一些客戶端鉤子，使用者可以執行這些鉤子來通知他們何時正在做伺服器可能拒絕的事情。這樣，他們可以在提交之前糾正任何問題，並且在這些問題變得更難修復之前。由於鉤子不會隨專案克隆一起傳輸，你必須以其他方式分發這些指令碼，然後讓你的使用者將它們複製到他們的 .git/hooks 目錄並使其可執行。你可以在專案內部或在單獨的專案中分發這些鉤子，但 Git 不會自動設定它們。

首先，你應該在每次提交記錄之前檢查你的提交訊息，這樣你就能知道伺服器不會因為格式錯誤的提交訊息而拒絕你的更改。要做到這一點，你可以新增 commit-msg 鉤子。如果你讓它從作為第一個引數傳遞的檔案中讀取訊息並與模式進行比較，如果沒有匹配，你可以強制 Git 中止提交

#!/usr/bin/env ruby
message_file = ARGV[0]
message = File.read(message_file)

$regex = /\[ref: (\d+)\]/

if !$regex.match(message)
  puts "[POLICY] Your message is not formatted correctly"
  exit 1
end

如果該指令碼已就位（在 .git/hooks/commit-msg 中）且可執行，並且你提交的訊息格式不正確，你會看到這個

$ git commit -am 'Test'
[POLICY] Your message is not formatted correctly

在這種情況下沒有完成任何提交。但是，如果你的訊息包含正確的模式，Git 將允許你提交

$ git commit -am 'Test [ref: 132]'
[master e05c914] Test [ref: 132]
 1 file changed, 1 insertions(+), 0 deletions(-)

接下來，你要確保你沒有修改超出 ACL 範圍的檔案。如果你的專案的 .git 目錄包含你之前使用的 ACL 檔案副本，那麼以下 pre-commit 指令碼將為你強制執行這些約束

#!/usr/bin/env ruby

$user    = ENV['USER']

# [ insert acl_access_data method from above ]

# only allows certain users to modify certain subdirectories in a project
def check_directory_perms
  access = get_acl_access_data('.git/acl')

  files_modified = `git diff-index --cached --name-only HEAD`.split("\n")
  files_modified.each do |path|
    next if path.size == 0
    has_file_access = false
    access[$user].each do |access_path|
    if !access_path || (path.index(access_path) == 0)
      has_file_access = true
    end
    if !has_file_access
      puts "[POLICY] You do not have access to push to #{path}"
      exit 1
    end
  end
end

check_directory_perms

這大致與伺服器端指令碼相同，但有兩個重要區別。首先，ACL 檔案在不同的位置，因為此指令碼從你的工作目錄執行，而不是從你的 .git 目錄。你必須將 ACL 檔案的路徑從這個

access = get_acl_access_data('acl')

更改為這個

access = get_acl_access_data('.git/acl')

另一個重要的區別是你獲取已更改檔案列表的方式。因為伺服器端方法檢視提交日誌，而此時提交尚未記錄，所以你必須從暫存區獲取檔案列表。而不是

files_modified = `git log -1 --name-only --pretty=format:'' #{ref}`

你必須使用

files_modified = `git diff-index --cached --name-only HEAD`

但這些是僅有的兩個區別——否則，指令碼的工作方式相同。一個警告是，它期望你在本地以與推送到遠端機器相同的使用者身份執行。如果不同，你必須手動設定 $user 變數。

我們在這裡還可以做另一件事，那就是確保使用者不推送非快進引用。要獲得一個非快進的引用，你必須重定向（rebase）過去一個你已經推送的提交，或者嘗試將不同的本地分支推送到相同的遠端分支。

據推測，伺服器已經配置了 receive.denyDeletes 和 receive.denyNonFastForwards 來強制執行此策略，因此你唯一能嘗試捕獲的意外情況是重定向（rebase）已經推送的提交。

這是一個檢查此情況的 pre-rebase 指令碼示例。它獲取你即將重寫的所有提交列表，並檢查它們是否存在於你的任何遠端引用中。如果它發現其中一個可以從你的某個遠端引用中訪問到，它將中止重定向（rebase）。

#!/usr/bin/env ruby

base_branch = ARGV[0]
if ARGV[1]
  topic_branch = ARGV[1]
else
  topic_branch = "HEAD"
end

target_shas = `git rev-list #{base_branch}..#{topic_branch}`.split("\n")
remote_refs = `git branch -r`.split("\n").map { |r| r.strip }

target_shas.each do |sha|
  remote_refs.each do |remote_ref|
    shas_pushed = `git rev-list ^#{sha}^@ refs/remotes/#{remote_ref}`
    if shas_pushed.split("\n").include?(sha)
      puts "[POLICY] Commit #{sha} has already been pushed to #{remote_ref}"
      exit 1
    end
  end
end

此指令碼使用了一種在 修訂版本選擇中未涵蓋的語法。你可以透過執行此命令獲取已推送的提交列表

`git rev-list ^#{sha}^@ refs/remotes/#{remote_ref}`

SHA^@ 語法解析為該提交的所有父級。你正在尋找任何可以從遠端的最新提交訪問到，但不能從你嘗試推送的任何 SHA-1 的任何父級訪問到的提交——這意味著它是一個快進（fast-forward）。

這種方法的主要缺點是它可能非常慢，而且通常沒有必要——如果你不嘗試使用 -f 強制推送，伺服器會警告你並且不接受推送。然而，這是一個有趣的練習，理論上可以幫助你避免以後可能需要回溯修復的重定向（rebase）。

scroll-to-top