Changes between Version 5 and Version 6 of 0.12/TracRepositoryAdmin

Timestamp:

Feb 2, 2010, 11:45:58 PM (14 years ago)

Author:

Remy Blank

Comment:

Added a quickstart section and a section about repository synchronization.

0.12/TracRepositoryAdmin

@@ -1 @@
-= Repository Administration
+= Repository Administration =
 [[PageOutline(2-3)]]
 
-== Specifying repositories
+== Quick start ==
+
+ * Manage repositories in the "Repository" admin panel, with `trac-admin` or in the `[repositories]` section of [wiki:TracIni#repositories-section trac.ini].
+ * Set up a call to `trac-admin $ENV changeset added $REPO $REV` in the post-commit hook of each repository. Additionally, add a call to `trac-admin $ENV changeset modified $REPO $REV` in the post-revprop-change hook of repositories allowing revision property changes.
+ * Set the `[trac] repository_sync_per_request` option to an empty value to disable per-request syncing.
+
+== Specifying repositories ==
 Starting with 0.12, Trac can handle more than one repository per environment. The pre-0.12 way of specifying the repository with the `repository_dir` and `repository_type` options in the `[trac]` section of [wiki:TracIni trac.ini] is still supported, but two new mechanisms allow including additional repositories into an environment.
 
@@ -23 +29 @@
 The `name` attribute and one of `alias` or `dir` are mandatory. All others are optional.
 
-=== In `trac.ini`
+=== In `trac.ini` ===
 Repositories and repository attributes can be specified in the `[repositories]` section of [wiki:TracIni#repositories-section trac.ini]. Every attribute consists of a key structured as `{name}.{attribute}` and the corresponding value separated with an equal sign (`=`). The name of the default repository is empty.
 
@@ -45 +51 @@
 Note that `name.alias = target` makes `name` an alias for the `target` repo, not the other way around.
 
-=== In the database
+=== In the database ===
 Repositories can also be specified in the database, using either the "Repositories" admin panel under "Version Control", or the `trac-admin $ENV repository` commands.
 
@@ -67 +73 @@
 
 == Repository synchronization
+Prior to 0.12, Trac synchronized its cache with the repository on every request. This approach is not practical anymore with multiple repositories. For this reason, explicit synchronization through post-commit hooks was added. This also provides new functionality in the form of a repository listener extension point that is called when a changeset is added or modified, and can be used by plugins to perform actions on commit.
+
+=== Explicit synchronization ===
+This is the preferred method of repository synchronization. It requires setting the `[trac]  repository_sync_per_request` option in [wiki:TracIni#trac-section trac.ini] to an empty value, and adding a call to `trac-admin` in the post-commit hook of each repository. Additionally, if a repository allows changing revision metadata, a call to `trac-admin` must be added to the post-revprop-change hook as well.
+
+ `changeset added <repos> <rev> [...]`::
+   Notify Trac that one or more changesets have been added to a repository.
+
+ `changeset modified <repos> <rev> [...]`::
+   Notify Trac that metadata on one or more changesets in a repository has been modified.
+
+The `<repos>` argument can be either a repository name (use "`(default)`" for the default repository) or the path to the repository.
+
+The following example is a complete post-commit script for Subversion on Unix. It should marked executable and placed in the `hooks` directory of the repository, with the file name `post-commit`.
+{{{
+#!sh
+#!/bin/sh
+/usr/bin/trac-admin /path/to/env changeset added "$1" "$2"
+}}}
+On Windows (`post-commit.cmd`):
+{{{
+#!application/x-dos-batch
+@C:\Python26\Scripts\trac-admin.exe C:\path\to\env changeset added "%1" "%2"
+}}}
+
+The post-revprop-change hook for Subversion is very similar. On Unix:
+{{{
+#!sh
+#!/bin/sh
+/usr/bin/trac-admin /path/to/env changeset modified "$1" "$2"
+}}}
+On Windows (`post-revprop-change.cmd`):
+{{{
+#!application/x-dos-batch
+@C:\Python26\Scripts\trac-admin.exe C:\path\to\env changeset modified "%1" "%2"
+}}}
+
+See the [http://svnbook.red-bean.com/en/1.5/svn.reposadmin.create.html#svn.reposadmin.create.hooks section about hooks] in the Subversion book for more information. Other repository types will require different hook setups. Please see the plugin documentation for specific instructions.
+
+=== Per-request synchronization ===
+If the post-commit hooks are not available, the environment can be set up for per-request synchronization. In that case, the `[trac] repository_sync_per_request` option in [wiki:TracIni#trac-section trac.ini] must be set to a comma-separated list of repository names to be synchronized.
+
+Note that in this case, the changeset listener extension point is not called, and therefore plugins using it will not work correctly.