Bug#932696: Please document Haskell team style Vcs-Git sytax
- To: 932696@bugs.debian.org
- Subject: Bug#932696: Please document Haskell team style Vcs-Git sytax
- From: Russ Allbery <rra@debian.org>
- Date: Thu, 01 Apr 2021 13:40:06 -0700
- Message-id: <[🔎] 8735w9oi1l.fsf@hope.eyrie.org>
- Reply-to: Russ Allbery <rra@debian.org>, 932696@bugs.debian.org
- In-reply-to: <23860.61465.584149.419072@chiark.greenend.org.uk> (Ian Jackson's message of "Mon, 22 Jul 2019 00:07:05 +0100")
- References: <23860.61465.584149.419072@chiark.greenend.org.uk> <23860.61465.584149.419072@chiark.greenend.org.uk>
Ian Jackson <ijackson@chiark.greenend.org.uk> writes:
> Package: debian-policy
> Version: 4.4.0.1
> Many packages' .dscs contain something like this:
> Source: bustle
> Version: 0.7.4-1
> Vcs-Git: https://salsa.debian.org/haskell-team/DHG_packages.git [p/bustle]
> The semantics do not appearr to be documented in policy.
Reminder that this proposed patch needs one more second to be merged into
the next release of Policy.
--
Russ Allbery (rra@debian.org) <https://www.eyrie.org/~eagle/>
diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst
index a21a510..2a2e364 100644
--- a/policy/ch-controlfields.rst
+++ b/policy/ch-controlfields.rst
@@ -972,11 +972,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 specifies the relative path to the top of the packaging
+ tree (the parent directory of the ``debian`` directory). If no path
+ is specified, it defaults to ``.`` (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 multiple version control
Reply to: