Bug#932696: Please document Haskell team style Vcs-Git sytax
- To: Ian Jackson <ijackson@chiark.greenend.org.uk>
- Cc: Jonathan Nieder <jrnieder@gmail.com>, 932696@bugs.debian.org, Debian Haskell Group <pkg-haskell-maintainers@lists.alioth.debian.org>
- Subject: Bug#932696: Please document Haskell team style Vcs-Git sytax
- From: Russ Allbery <rra@debian.org>
- Date: Wed, 23 Oct 2019 13:58:50 -0700
- Message-id: <[🔎] 871rv3ji0l.fsf@hope.eyrie.org>
- Reply-to: Russ Allbery <rra@debian.org>, 932696@bugs.debian.org
- In-reply-to: <23887.3759.851828.414699@chiark.greenend.org.uk> (Ian Jackson's message of "Sat, 10 Aug 2019 19:36:31 +0100")
- References: <handler.932696.B.15637504299768.ack@bugs.debian.org> <23860.62586.367455.536118@chiark.greenend.org.uk> <87a7d67nn7.fsf@hope.eyrie.org> <23861.57090.679471.952231@chiark.greenend.org.uk> <87ftmy6o08.fsf@hope.eyrie.org> <23860.61465.584149.419072@chiark.greenend.org.uk> <23861.58439.213768.966943@chiark.greenend.org.uk> <20190723041357.GA246192@google.com> <878sspv0tz.fsf@hope.eyrie.org> <20190723044237.GB246192@google.com> <8736ixuzfa.fsf@hope.eyrie.org> <23887.3759.851828.414699@chiark.greenend.org.uk> <23860.61465.584149.419072@chiark.greenend.org.uk>
Control: tags -1 patch
Ian Jackson <ijackson@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@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@debian.org) <https://www.eyrie.org/~eagle/>
Reply to: