Git: Added ability to update to a specific tree-ish

1 files changed, 32 insertions, 3 deletions

diff --git a/doc/server/plugins/version/git.txt b/doc/server/plugins/version/git.txt
index b3c469d6c..3f7ab9d9b 100644
--- a/doc/server/plugins/version/git.txt
+++ b/doc/server/plugins/version/git.txt
@@ -20,9 +20,38 @@ it will include the current repository revision in the
 reports/statistics.
 
 Additionally, if the ``GitPython`` library is installed, the Git
-plugin exposes an additional XML-RPC method call, ``Git.Update``,
-which updates the working copy to the latest version in the remote
-origin.
+plugin exposes an additional XML-RPC method call, ``Git.Update``.
+With no arguments, ``Git.Update`` updates the working copy to the
+latest version in the remote tracking branch.  If the current working
+copy doesn't have a remote tracking branch, then nothing is done.
+
+``Git.Update`` can also be given a single argument, the name of a git
+tree-ish (branch, tag, ref, commit, etc.) to check out.  When this is
+done, the new working is updated as well.
+
+For example::
+
+    bcfg2-admin xcmd Git.Update master
+
+This checks out the ``master`` branch and updates it to the latest
+data from the remote ``master`` (if applicable).  If you then run::
+
+    bcfg2-admin xcmd Git.Update
+
+This updates to the latest remote data without changing branches.
+Then::
+
+    bcfg2-admin xcmd Git.Update dd0bb776c
+
+This checks out the specified commit.  Subsequently::
+
+    bcfg2-admin xcmd Git.Update
+
+This does nothing, because the working copy is now in "detached HEAD"
+state, and there can be no remote tracking branch to update from.
+
+To put it another way, once you tell ``Git.Update`` which tree-ish to
+checkout, it stays on that tree-ish until you tell it otherwise.
 
 Enabling the Git plugin
 =======================