Please document Haskell team style Vcs-Git sytax

[Russ Allbery]

Control: tags -1 patch

Ian Jackson <ijackson at chiark.greenend.org.uk> writes:

> I found myself trying to implement what I had suggested earlier and
> ran up against the question of what to do about [ ] in optional
> values.

> I decided to use this regexp
> +	$vcsgiturl =~ s/\s+\[[^][]*\]//g;
> (I need to strip the information, not use it.)  That hopes paths do
> not contain [ ] but permits (and eats) spaces inside the [ ].

> I'm inclined to think that these questions show that my original
> proposal was not brilliant and that your idea is better.

> HTH.

Here's proposed wording that documents only the already-in-use path
syntax.  (We're probably overdue for introducing ABNF into Policy so that
we can properly specify the syntax of things, but I didn't attempt to do
that here.)

Author: Russ Allbery <rra at debian.org>
Date:   Wed Oct 23 13:56:06 2019

    Add support for paths in Vcs-Git
    
    Closes: #932696

diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst
index 60edc82..297f5c3 100644
--- a/policy/ch-controlfields.rst
+++ b/policy/ch-controlfields.rst
@@ -973,11 +973,33 @@ repository where the Debian source package is developed.
     - Mtn (Monotone)
     - Svn (Subversion)
 
-    In the case of Git and Mercurial, the value consists of a URL,
-    optionally followed by the word ``-b`` and the name of a branch in
-    the indicated repository, following the syntax of the ``git clone``
-    or ``hg clone`` command. If no branch is specified, the packaging
-    should be on the default branch.
+    In the case of Git, the value must have the following syntax::
+
+        <url> [ " -b " <branch> ] [ "[" <path> "]" ]
+
+    where the portions enclosed in brackets are optional and the portions
+    enclosed in double quotes are literal strings.  ``<url>`` indicates
+    the repository.  If the ``<branch>`` stanza is present, it names a
+    branch in the indicated repository.  If no branch is specified, the
+    packaging should be on the default branch.  If the ``<path>`` stanza
+    is present, it must be a relative path naming a subdirectory in that
+    repository and branch.  If no path is specified, the ``debian``
+    directory containing the packaging is expected to be at the top level
+    of the indicated repository and branch.
+
+    For example::
+
+        Vcs-Git: https://example.org/repo -b debian [p/package]
+
+    indicates a subdirectory named ``p/package`` in the ``debian`` branch
+    of the repository at ``https://example.org/repo``.
+
+    In the case of Mercurial, the value must have the following syntax::
+
+        <url> [ " -b " <branch> ]
+
+    This is interpreted the same way as the Git syntax except a path
+    within the repository is not supported.
 
     A package control file must not have more than one ``Vcs-<type>``
     field.  If the package is maintained in multple version control


-- 
Russ Allbery (rra at debian.org)              <https://www.eyrie.org/~eagle/>