版本库管理

快速入门

• 为您将使用的版本控制系统启用相应的版本库连接器。
• 通过版本库管理页面、使用trac-admin或编辑trac.ini中的[repositories]部分来添加版本库。
• 如果使用缓存版本库，请将版本库与缓存同步。
• 配置您的版本库钩子以同步版本库。或者，您也可以在每次请求时同步或禁用缓存版本库的使用，这两种方法都存在性能缺陷和功能受限，但更容易配置。

启用组件

Trac 分发的版本控制系统支持由可选组件提供，这些组件默认禁用（自 1.0 版起）。如果您希望使用 Subversion 和 Git，必须明确启用它们。

可以通过将以下内容添加到您的trac.ini的[components]部分，或通过插件管理页面启用组件来启用版本控制系统。

tracopt.versioncontrol.svn.* = enabled

tracopt.versioncontrol.git.* = enabled

指定版本库

Trac 支持每个环境包含多个版本库，并且这些版本库可能对应不同的版本控制系统。每个版本库必须在版本库配置提供程序中定义。Trac 包含的版本库提供程序有数据库存储、trac.ini 配置文件和GitWeb 配置文件。其他提供程序可作为插件使用。

您可以通过混合使用不同的提供程序来定义您的版本库，但每个版本库应仅在一个提供程序中定义。版本库名称在所有提供程序中必须是唯一的，重复的名称将被忽略。

可以定义版本库别名，它们充当指向真实版本库的“指针”。这在重命名版本库时很有用，可以避免旧名称的链接失效。

默认版本库

当导航到浏览源代码时，Trac 的版本库会列在版本库索引中。默认版本库首先显示，其后是版本库索引。TracLinks在路径规范中没有版本库名称时（例如[1]而不是[1/repos1]）指的是默认版本库。非默认版本库的 TracLinks 必须在路径规范中包含版本库名称。

在版本库管理页面，通过将名称属性留空来指定默认版本库。从命令行，使用字符串(default)或""来指定默认版本库。在TracIni中，通过将每个{name}.{attribute}选项的{name}留空来指定默认版本库（例如.dir = /path/to/dir）。

版本库属性

可以为每个版本库指定多个属性，并且可以通过插件提供额外的属性。版本库的name以及alias或dir属性之一是强制性的。所有其他属性都是可选的。

支持以下属性

属性	描述
alias	定义一个指向真实版本库的别名。所有引用该别名的TracLinks都会解析到所指向的版本库。请注意，不支持多重间接引用，因此别名必须始终指向一个真实版本库。alias和dir属性互斥。
cached	对于支持缓存的版本控制系统，指定应使用版本库缓存。对于支持缓存的版本控制系统，默认为true。
description	在description属性中指定的文本将显示在源代码浏览器中版本库的顶级条目下方。它支持WikiFormatting。
dir	dir属性指定了版本库在文件系统中的位置。alias和dir属性互斥。
hidden	当设置为true时，版本库将在源代码浏览器中的版本库索引页面中隐藏。仍然可以浏览该版本库，并且引用该版本库的链接仍然有效。
sync_per_request	当设置为true时，版本库将在每个请求时同步（隐式同步）。通常不建议这样做。有关显式同步和隐式同步的比较，请参阅版本库同步。该属性默认为false。
type	type属性指定版本库使用的版本控制系统。Trac 支持 Subversion 和 Git，并且插件增加了对其他几个系统的支持。如果未指定type，它将默认为[versioncontrol] default_repository_type选项的值。
url	url属性指定用于从版本库检出的根 URL。指定后，“版本库 URL”链接会添加到源代码浏览器中的上下文导航链接中，该链接可以复制到用于创建工作副本的工具中。

限定范围的版本库

对于某些版本控制系统，不仅可以在dir属性中指定版本库的路径，还可以指定版本库内的范围。Trac 然后将只显示与该范围下的文件和变更集相关的信息。范围通过追加相对于版本库根目录的路径来指定。Trac 的 Subversion 后端支持此功能。

例如，假设一个版本库位于文件系统路径/var/svn/repos1，并且版本库根目录下有多个目录：/proj1、/proj2等。以下配置会将版本库范围限定为/proj1

proj1.dir = /var/svn/repos1/proj1
proj1.type = svn

对于其他版本库类型，请查阅相应插件的文档。

在数据库中

版本库也可以在数据库中指定，可以使用版本控制下的版本库管理页面，或者使用trac-admin $ENV repository命令。

管理面板显示 Trac 环境中定义的所有版本库列表。它允许添加版本库和别名、编辑版本库属性以及删除版本库。请注意，在trac.ini中定义的版本库会显示但无法编辑。

以下trac-admin命令可用于从命令行执行版本库操作。

repository add <版本库> <目录> [类型]

添加位于<dir>的版本库<repos>，并可选地指定其类型。

repository alias <名称> <目标>

为版本库<target>创建别名<name>。

repository remove <版本库>

移除版本库<repos>。

repository set <版本库> <键> <值>

为版本库<repos>设置属性<key>为<value>。

请注意，默认版本库的名称为空，因此从 shell 运行trac-admin时需要加引号。或者，也可以使用名称(default)，例如在交互模式下运行trac-admin时。

在 trac.ini 中

版本库和版本库属性可以在trac.ini的[repositories]部分中指定。每个属性由一个结构为{name}.{attribute}的键和用等号（=）分隔的相应值组成。默认版本库的名称为空。

在trac.ini中指定版本库的主要优点是它们可以从全局配置继承。如果在环境初始化时版本库连接器已启用，在trac.ini中定义的缓存版本库将自动同步。一个缺点是，由于用于解析trac.ini的ConfigParser类的限制，版本库名称始终是小写。

以下示例定义了两个名为project和lib的 Subversion 版本库，并将project的别名设置为默认版本库。这是一个典型用例，其中 Trac 环境之前只有一个版本库（project版本库），后来转换为多个版本库。该别名确保在更改之前存在的链接仍然解析到project版本库。

[repositories]
project.dir = /var/repos/project
project.description = This is the ''main'' project repository.
project.type = svn
project.url = http://example.com/svn/project
project.hidden = true

lib.dir = /var/repos/lib
lib.description = This is the secondary library code.
lib.type = svn
lib.url = http://example.com/svn/lib

.alias = project

请注意，name.alias = target使得name成为target版本库的别名，而不是反过来。

在 GitWeb 中

​GitWeb是一个随 Git 提供的 CGI 脚本，用于版本库的基于 Web 的可视化。Trac 可以读取 GitWeb 格式的project.lists文件。配置通过trac.ini的[gitweb-repositories]部分完成。

版本库缓存

缓存可以提高浏览版本库、查看日志和查看变更集的性能。缓存版本库必须使用显式同步或隐式同步进行同步。在搜索变更集时，仅搜索缓存的版本库。

支持缓存的版本库默认会被缓存。Subversion 和 Git 后端支持缓存。​Mercurial 插件尚不支持缓存（​#8417）。要禁用缓存，请将cached属性设置为false。

添加缓存版本库后，必须使用trac-admin $ENV repository resync命令填充缓存。

repository resync <版本库>

将 Trac 与版本库重新同步。

版本库同步

可以使用显式同步或隐式同步。隐式同步配置起来更简单，但可能会导致性能明显下降。变更集添加和修改事件无法通过隐式同步触发，因此提交工单更新器将不可用。

显式同步

这是首选的版本库同步方法。它要求在每个版本库的post-commit钩子中添加对trac-admin的调用。此外，如果版本库允许更改修订元数据，则还必须在post-revprop-change钩子中添加对trac-admin的调用。

changeset added <版本库> <修订版本> […]

通知 Trac 已向版本库添加一个或多个变更集。

changeset modified <版本库> <修订版本> […]

通知 Trac 版本库中一个或多个变更集的元数据已修改。

<repos>参数可以是版本库名称（默认版本库使用"(default)"）或版本库的路径。

请注意，如果您将环境变量PYTHON_EGG_CACHE从默认位置更改，则在调用trac-admin之前，您可能需要将其设置为与 Web 服务器配置相同的值。有关更多信息，请参阅TracPlugins。

Subversion

使用 trac-svn-hook

在 Unix 环境中，配置显式同步最简单的方法是使用​contrib/trac-svn-hook脚本。trac-svn-hook异步启动trac-admin，以避免减慢提交和日志编辑操作。该脚本附带了许多安全检查和使用建议。输出写入环境log目录中以svn-hooks-为前缀的日志文件，这可以使配置问题更容易调试。

目前还没有适用于 Windows 的等效trac-svn-hook.bat，但该脚本可以通过 Cygwin 的 bash 运行。trac-svn-hook的文档头部包含一个 Cygwin 配置示例。

按照脚本文档头部中的帮助配置trac-svn-hook。您至少需要设置TRAC_ENV变量，对于非标准安装或虚拟环境，可能还需要设置TRAC_PATH和TRAC_LD_LIBRARY_PATH。

使用​钩子脚本环境配置，在 Subversion 1.8 及更高版本中配置钩子环境变量甚至更容易。与其直接编辑trac-svn-hook来设置环境变量，或者从调用trac-svn-hook的钩子中导出它们，不如通过版本库的conf/hooks-env文件进行配置。

以下是一个示例，使用/usr/local/venv处的 Python 虚拟环境

[default]
TRAC_ENV=/var/trac/project-1
TRAC_PATH=/usr/local/venv/bin

编写您自己的钩子脚本

以下示例是 Subversion 的完整 post-commit 和 post-revprop-change 脚本。应根据特定环境进行编辑，标记为可执行（如适用），并放置在每个版本库的hooks目录中。在 Unix 上（post-commit）

#!/bin/sh
export PYTHON_EGG_CACHE="/path/to/dir"
/usr/bin/trac-admin /path/to/env changeset added "$1" "$2"

调整trac-admin的实际路径。在 Windows 上（post-commit.cmd）

@C:\Python26\Scripts\trac-admin.exe C:\path\to\env changeset added "%1" "%2"

Subversion 的 post-revprop-change 钩子非常相似。在 Unix 上（post-revprop-change）

#!/bin/sh
export PYTHON_EGG_CACHE="/path/to/dir"
/usr/bin/trac-admin /path/to/env changeset modified "$1" "$2"

在 Windows 上（post-revprop-change.cmd）

@C:\Python26\Scripts\trac-admin.exe C:\path\to\env changeset modified "%1" "%2"

上述 Unix 变体假设运行 Subversion 提交的用户对 Trac 环境具有写入权限，这在标准配置中是这样的，即版本库和 Trac 都由 Web 服务器提供服务。如果您通过其他方式访问版本库，例如svn+ssh://，您可能需要以不同的权限运行trac-admin，例如使用sudo。

有关更多信息，请参阅 Subversion 手册中​关于钩子的部分。其他版本库类型需要不同的钩子配置。

Git

​Git 钩子可以以相同的方式用于 Git 版本库的显式同步。

如果您的版本库是只接受推送的，请将以下内容添加到版本库中的hooks/post-receive文件

#!/bin/sh
tracenv=/path/to/env  # set to your Trac environment's path
repos=                # set to your repository's name
while read oldrev newrev refname; do
    if [ "$oldrev" = 0000000000000000000000000000000000000000 ]; then
        git rev-list --reverse "$newrev" --
    else
        git rev-list --reverse "$newrev" "^$oldrev" --
    fi | xargs trac-admin "$tracenv" changeset added "$repos"
done

repos变量是版本库名称（默认版本库使用"(default)"）。

或者，如果您的 Git 版本库是直接在托管 Trac 的机器上进行提交的，请将以下内容添加到您的 Git 版本库中的hooks/post-commit文件

#!/bin/sh
tracenv=/path/to/env  # set to your Trac environment's path
repos=                # set to your repository's name
REV=$(git rev-parse HEAD)
trac-admin "$tracenv" changeset added "$repos" $REV

如果您只通过推送来更新版本库，则post-commit钩子将不起作用。

请务必将钩子脚本设置为可执行。

Mercurial

对于 Mercurial，将以下条目添加到 Trac 访问的每个版本库的.hgrc文件中（如果​TracMercurial安装在 Trac 的plugins目录中，请下载​hooks.py并将其放置在可访问的位置）

[hooks]
; If mercurial-plugin is installed globally
commit = python:tracext.hg.hooks.add_changesets
changegroup = python:tracext.hg.hooks.add_changesets

; If mercurial-plugin is installed in a Trac plugins directory
commit = python:/path/to/hooks.py:add_changesets
changegroup = python:/path/to/hooks.py:add_changesets

[trac]
env = /path/to/env
trac-admin = /path/to/trac-admin

按请求同步

如果 post-commit 钩子不可用，可以设置环境以实现按请求同步。数据库和trac.ini中每个版本库的sync_per_request属性必须设置为true。

请注意，在这种情况下，不会调用变更集侦听器扩展点，因此依赖于变更集添加和修改事件的插件将无法正常工作。例如，自动变更集引用无法与隐式同步一起使用。

工单中自动引用变更集

每当将更改提交到版本库时，您可以自动将变更集引用添加为工单注释。提交说明需要包含以下模式之一

• Refs #123 - 在#123工单中引用此变更集
• Fixes #123 - 引用此变更集并以默认状态已修复关闭#123工单

此功能需要安装显式同步中所述的 post-commit 钩子，并通过插件管理面板启用可选的提交更新器组件，或者将以下行添加到您的trac.ini的[components]部分

tracopt.ticket.commit_updater.* = enabled

有关更多信息，请参阅插件管理面板中CommitTicketUpdater组件的文档和​CommitTicketUpdater页面。

故障排除

我的 trac-post-commit-hook 不再工作

您现在必须使用来自tracopt.ticket.commit_updater.*的可选组件，您可以通过插件管理页面激活它们，或直接修改 trac.ini 中的[components]部分。请务必使用显式同步。

有关更多故障排除技巧，请参阅​CommitTicketUpdater#Troubleshooting。

Git 控制文件丢失

如果您的版本库无法浏览，并且您在日志中找到类似以下消息

2017-08-08 10:49:17,339 Trac[PyGIT] ERROR: GIT control files missing in '/path/to/git-repository'
2017-08-08 10:49:17,339 Trac[git_fs] ERROR: GitError: GIT control files not found, maybe wrong directory?

首先检查您的版本库路径是否正确。如果路径正确，您可能存在权限问题，导致 Web 服务器无法访问版本库。您可以使用 Git 验证版本库。在 Debian-like 的 Linux 操作系统上，以下命令应该会有所帮助

$ sudo -u www-data git --git-dir=/path/to/git-repository fsck

在其他平台上，您可能需要修改命令以使用 Web 服务器运行的用户。