diff --git a/doc/cabal-package-description-file.rst b/doc/cabal-package-description-file.rst index 6ae467b4774..b9b0cb172f3 100644 --- a/doc/cabal-package-description-file.rst +++ b/doc/cabal-package-description-file.rst @@ -2747,22 +2747,28 @@ The :ref:`VCS fields` of ``source-repository`` are: This field is required. + .. include:: vcs/kind.rst + .. pkg-field:: location: VCS location This field is required. -.. pkg-field:: module: token + .. include:: vcs/location.rst - CVS requires a named module, as each CVS server can host multiple - named repositories. +.. pkg-field:: module: token This field is required for the CVS repository type and should not be used otherwise. + CVS requires a named module, as each CVS server can host multiple + named repositories. + .. pkg-field:: branch: VCS branch This field is optional. + .. include:: vcs/branch.rst + .. pkg-field:: tag: VCS tag This field is required for the ``this`` repository kind. @@ -2770,10 +2776,13 @@ The :ref:`VCS fields` of ``source-repository`` are: This might be used to indicate what sources to get if someone needs to fix a bug in an older branch that is no longer an active head branch. + .. include:: vcs/tag.rst + .. pkg-field:: subdir: VCS subdirectory This field is optional but, if given, specifies a single subdirectory. + .. include:: vcs/subdir.rst .. _setup-hooks: diff --git a/doc/cabal-project-description-file.rst b/doc/cabal-project-description-file.rst index f024e540010..8e4a150b205 100644 --- a/doc/cabal-project-description-file.rst +++ b/doc/cabal-project-description-file.rst @@ -269,23 +269,33 @@ The :ref:`VCS fields` of ``source-repository-package`` are: This field is required. + .. include:: vcs/kind.rst + .. cfg-field:: location: VCS location This field is required. + .. include:: vcs/location.rst + .. cfg-field:: branch: VCS branch This field is optional. + .. include:: vcs/branch.rst + .. cfg-field:: tag: VCS tag This field is optional. + .. include:: vcs/tag.rst + .. cfg-field:: subdir: VCS subdirectory list Look in one or more subdirectories of the repository for cabal files, rather than the root. This field is optional. + .. include:: vcs/subdir.rst + .. cfg-field:: post-checkout-command: command Run command in the checked out repository, prior sdisting. diff --git a/doc/vcs/branch.rst b/doc/vcs/branch.rst new file mode 100644 index 00000000000..5908367c130 --- /dev/null +++ b/doc/vcs/branch.rst @@ -0,0 +1,8 @@ +.. + VCS branch + +Many source control systems support the notion of a branch, as a distinct +concept from having repositories in separate locations. For example CVS, SVN and +git use branches while darcs uses different locations for different branches. If +you need to specify a branch to identify a your repository then specify it in +this field. diff --git a/doc/vcs/fields.rst b/doc/vcs/fields.rst new file mode 100644 index 00000000000..9ce0d4c840a --- /dev/null +++ b/doc/vcs/fields.rst @@ -0,0 +1,34 @@ +.. + VCS common fields + +Most of the version control system (VCS) fields types are common to both +``source-repository`` and ``source-repository-package`` stanzas. + +.. list-table:: + :header-rows: 1 + :widths: 30 30 40 + + * - Field Name + - source-repository (head|this) + - source-repository-package + * - type + - [x] + - [x] + * - location + - [x] + - [x] + * - branch + - [x] + - [x] + * - tag + - [x] + - [x] + * - subdir + - [x] (0 or 1) + - [x] (0 or 1 for each dependency) + * - module (CVS only) + - [x] + - [_] + * - post-checkout-command + - [_] + - [x] diff --git a/doc/vcs/kind.rst b/doc/vcs/kind.rst new file mode 100644 index 00000000000..e87d55ae49e --- /dev/null +++ b/doc/vcs/kind.rst @@ -0,0 +1,19 @@ +.. + VCS kind + +Cabal supports specifying different information for various common source +control systems. This is the name of the source control system used for a +repository. The currently recognised types are: + +- ``darcs`` +- ``git`` +- ``svn`` +- ``cvs`` +- ``mercurial`` (or alias ``hg``) +- ``bazaar`` (or alias ``bzr``) +- ``arch`` +- ``monotone`` +- ``pijul`` + +The VCS kind will determine what other fields are appropriate to specify for a +particular version control system. diff --git a/doc/vcs/location.rst b/doc/vcs/location.rst new file mode 100644 index 00000000000..df32ffff093 --- /dev/null +++ b/doc/vcs/location.rst @@ -0,0 +1,9 @@ +.. + VCS location + +The location of the repository, usually a URL but the exact form of this field +depends on the repository type. For example: + +- for Darcs: ``http://code.haskell.org/foo/`` +- for Git: ``https://github.com/foo/bar.git`` +- for CVS: ``anoncvs@cvs.foo.org:/cvs`` diff --git a/doc/vcs/subdir.rst b/doc/vcs/subdir.rst new file mode 100644 index 00000000000..33ee731bb86 --- /dev/null +++ b/doc/vcs/subdir.rst @@ -0,0 +1,11 @@ +.. + VCS subdirectory + +A field of this type is always optional because it defaults to empty, which +corresponds to the root directory of the repository and is the same as +specifying ``.`` explicitly. + +Some projects put the sources for multiple packages inside a single VCS +repository. This field lets you specify the relative path from the root of the +repository to the top directory for the package, i.e. the directory containing +the package's ``.cabal`` file. diff --git a/doc/vcs/tag.rst b/doc/vcs/tag.rst new file mode 100644 index 00000000000..4ebdac6781c --- /dev/null +++ b/doc/vcs/tag.rst @@ -0,0 +1,5 @@ +.. + VCS tag + +A tag identifies a particular state of a source repository. The exact form of +the tag depends on the repository type. diff --git a/doc/version-control-fields.rst b/doc/version-control-fields.rst index 739905d4b8a..2298f22ed88 100644 --- a/doc/version-control-fields.rst +++ b/doc/version-control-fields.rst @@ -3,93 +3,31 @@ Version Control System Fields .. _vcs-fields: -Most of the version control system (VCS) fields types are common to both -``source-repository`` and ``source-repository-package`` stanzas. - -.. list-table:: - :header-rows: 1 - :widths: 30 30 40 - - * - Field Name - - source-repository (head|this) - - source-repository-package - * - type - - [x] - - [x] - * - location - - [x] - - [x] - * - branch - - [x] - - [x] - * - tag - - [x] - - [x] - * - subdir - - [x] (0 or 1) - - [x] (0 or 1 for each dependency) - * - module (CVS only) - - [x] - - [_] - * - post-checkout-command - - [_] - - [x] +.. include:: vcs/fields.rst .. _vcs-kind: VCS kind ^^^^^^^^ -Cabal supports specifying different information for various common source -control systems. This is the name of the source control system used for a -repository. The currently recognised types are: - -- ``darcs`` -- ``git`` -- ``svn`` -- ``cvs`` -- ``mercurial`` (or alias ``hg``) -- ``bazaar`` (or alias ``bzr``) -- ``arch`` -- ``monotone`` -- ``pijul`` - -The VCS kind will determine what other fields are appropriate to specify for a -particular version control system. +.. include:: vcs/kind.rst VCS location ^^^^^^^^^^^^ -The location of the repository, usually a URL but the exact form of this field -depends on the repository type. For example: - -- for Darcs: ``http://code.haskell.org/foo/`` -- for Git: ``https://github.com/foo/bar.git`` -- for CVS: ``anoncvs@cvs.foo.org:/cvs`` +.. include:: vcs/location.rst VCS branch ^^^^^^^^^^ -Many source control systems support the notion of a branch, as a distinct -concept from having repositories in separate locations. For example CVS, SVN and -git use branches while darcs uses different locations for different branches. If -you need to specify a branch to identify a your repository then specify it in -this field. +.. include:: vcs/branch.rst VCS tag ^^^^^^^ -A tag identifies a particular state of a source repository. The exact form of -the tag depends on the repository type. +.. include:: vcs/tag.rst VCS subdirectory ^^^^^^^^^^^^^^^^ -A field of this type is always optional because it defaults to empty, which -corresponds to the root directory of the repository and is the same as -specifying ``.`` explicitly. - -Some projects put the sources for multiple packages inside a single VCS -repository. This field lets you specify the relative path from the root of the -repository to the top directory for the package, i.e. the directory containing -the package's ``.cabal`` file. +.. include:: vcs/subdir.rst