[RFC 01/11] Add specification of git-vcs-* helper programs
From: Daniel Barkalow <barkalow@iabervon.org>
Signed-off-by: Daniel Barkalow <barkalow@iabervon.org>
Signed-off-by: Johan Herland <johan@herland.net>
---
Documentation/git-vcs.txt | 77 +++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 77 insertions(+), 0 deletions(-)
create mode 100644 Documentation/git-vcs.txt
diff --git a/Documentation/git-vcs.txt b/Documentation/git-vcs.txt
new file mode 100644
index 0000000..402c927
--- /dev/null
+++ b/Documentation/git-vcs.txt
@@ -0,0 +1,77 @@
+git-vcs(1)
+============
+
+NAME
+----
+git-vcs - Helper programs for interoperation with foreign systems
+
+SYNOPSIS
+--------
+'git vcs-<system>' <remote>
+
+DESCRIPTION
+-----------
+
+These programs are normally not used directly by end users, but are
+invoked by various git programs that interact with remote repositories
+when the repository they would operate on uses a foreign system.
+
+Each 'git vcs-<system>' is a helper for interoperating with a
+particular version control system. Different helpers have different
+capabilities (limited both by the particular helper and by the
+capabilities of the system they connect to), and they report what
+capabilities they support.
+
+These programs can store refs in refs/<system>/*, and arbitrary
+information in info/<system>.
+
+COMMANDS
+--------
+
+Commands are given by the caller on the helper's standard input, one per line.
+
+'capabilities'::
+ Outputs a single line with a list of feature names separated
+ by spaces. Each of these indicates a supported feature of the
+ helper, and the caller will only attempt operations that are
+ supported.
+
+'list'::
+ Outputs the names of refs, one per line. These may be
+ followed, after a single space, by "changed" or "unchanged",
+ indicating whether the foreign repository has changed from the
+ state in the ref. If the helper doesn't know, it doesn't have
+ to provide a value. (In particular, it shouldn't do expensive
+ operations, such as importing the content, to see whether it
+ matches.) Other information, not yet supported, may be output
+ as well, separated by single spaces.
+
+'import' ref::
+ Imports the given ref by outputting it in git-fast-import
+ format.
+
+'export' commit ref::
+ Sends the given commit to the foreign system, with the
+ location given by ref, and reimports it by outputting it in
+ git-fast-import format as the foreign system rendered it.
++
+All parents of commit must either have been created with 'import' or
+have been passed to 'export' previously. Depending on the features,
+there may be other restrictions on what may be exported.
+
+FEATURES
+--------
+
+'export'::
+ Helper supports exporting commits, at least exporting
+ non-merge commits whose parents are not the parents of any
+ other commit exported to the same branch or make in the other
+ system on the same branch.
+
+'export-branch'::
+ Helper supports creating new branches by exporting commits to
+ them.
+
+'export-merges'::
+ Helper supports exporting two-parent merges, where both
+ parents have already been exported successfully.
--
1.6.4.rc3.138.ga6b98.dirty
Johan Herland <johan@herland.net>