第二版

8.4 自定义 Git - Git 策略示例

Git 策略示例

在本节中，您将使用学到的知识来建立一个 Git 工作流程，该流程检查自定义提交消息格式，并只允许特定用户修改项目中的特定子目录。您将构建客户端脚本，帮助开发人员了解他们的推送是否会被拒绝，以及服务器脚本，真正执行这些策略。

我们展示的脚本是用 Ruby 编写的；部分原因是我们的知识惯性，也因为 Ruby 易于阅读，即使您不一定能编写它。但是，任何语言都可以使用 - Git 附带的所有示例钩子脚本都使用 Perl 或 Bash 编写，因此您可以通过查看示例来查看这些语言中钩子的许多示例。

服务器端钩子

所有服务器端工作都将在 hooks 目录中的 update 文件中进行。update 钩子在推送每个分支时运行一次，并接受三个参数

正在推送到的引用的名称
该分支所在的旧版本
正在推送的新版本

如果您通过 SSH 运行推送，则还可以访问正在执行推送的用户。如果您允许每个人都通过单个用户（如“git”）使用公钥身份验证进行连接，则可能需要为该用户提供一个 shell 包装器，该包装器根据公钥确定正在连接的用户，并相应地设置环境变量。在这里，我们假设连接用户位于 $USER 环境变量中，因此您的更新脚本首先收集您需要的所有信息

#!/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 <[email protected]> 1205815931 -0700
committer Scott Chacon <[email protected]> 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)

请记住，你在更新脚本的开头打印了它。你的脚本回显到 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 告诉你更新脚本以非零值退出，并且这就是拒绝你的推送的原因。最后，你有这个

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 变量。

我们还可以在这里做的一件事是确保用户不会推送非快进引用。要获取非快进引用，你必须在已经推送的提交之后重新设置基准，或者尝试将不同的本地分支推送到相同的远程分支。

据推测，服务器已经配置了 receive.denyDeletes 和 receive.denyNonFastForwards 来强制执行此策略，因此你唯一可以尝试捕获的意外情况是重新设置已经推送的提交的基准。

这是一个检查此情况的 pre-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 的任何父级访问的提交——这意味着它是一个快进。

这种方法的主要缺点是它可能非常慢，而且通常没有必要——如果你不尝试使用 -f 强制推送，服务器会警告你并且不会接受推送。但是，这是一个有趣的练习，理论上可以帮助你避免以后可能需要回退并修复的重新设置基准。

上页 | 下页

1. 入门

2. Git 基础

3. Git 分支

4. Git 服务器

5. 分布式 Git

6. GitHub

7. Git 工具

8. 自定义 Git

9. Git 与其他系统

10. Git 内部

A1. 附录 A：Git 在其他环境中的使用

A2. 附录 B：将 Git 嵌入到您的应用程序中