doc/version-control-fields.rst

   1 Version Control System Fields
   2 =============================
   3
   4 .. _vcs-fields:
   5
   6 Most of the version control system (VCS) fields types are common to both
   7 ``source-repository`` and ``source-repository-package`` stanzas.
   8
   9 .. list-table::
  10     :header-rows: 1
  11     :widths: 30 30 40
  12
  13     * - Field Name
  14       - source-repository (head|this)
  15       - source-repository-package
  16     * - type
  17       - [x]
  18       - [x]
  19     * - location
  20       - [x]
  21       - [x]
  22     * - branch
  23       - [x]
  24       - [x]
  25     * - tag
  26       - [x]
  27       - [x]
  28     * - subdir
  29       - [x] (0 or 1)
  30       - [x] (0 or 1 for each dependency)
  31     * - module (CVS only)
  32       - [x]
  33       - [_]
  34     * - post-checkout-command
  35       - [_]
  36       - [x]
  37
  38 .. _vcs-kind:
  39
  40 VCS kind
  41 ^^^^^^^^
  42
  43 Cabal supports specifying different information for various common source
  44 control systems. This is the name of the source control system used for a
  45 repository. The currently recognised types are:
  46
  47 -  ``darcs``
  48 -  ``git``
  49 -  ``svn``
  50 -  ``cvs``
  51 -  ``mercurial`` (or alias ``hg``)
  52 -  ``bazaar`` (or alias ``bzr``)
  53 -  ``arch``
  54 -  ``monotone``
  55 -  ``pijul``
  56
  57 The VCS kind will determine what other fields are appropriate to specify for a
  58 particular version control system.
  59
  60 VCS location
  61 ^^^^^^^^^^^^
  62
  63 The location of the repository, usually a URL but the exact form of this field
  64 depends on the repository type. For example:
  65
  66 -  for Darcs: ``http://code.haskell.org/foo/``
  67 -  for Git: ``https://github.com/foo/bar.git``
  68 -  for CVS: ``anoncvs@cvs.foo.org:/cvs``
  69
  70 VCS branch
  71 ^^^^^^^^^^
  72
  73 Many source control systems support the notion of a branch, as a distinct
  74 concept from having repositories in separate locations. For example CVS, SVN and
  75 git use branches while darcs uses different locations for different branches. If
  76 you need to specify a branch to identify a your repository then specify it in
  77 this field.
  78
  79 VCS tag
  80 ^^^^^^^
  81
  82 A tag identifies a particular state of a source repository.  The exact form of
  83 the tag depends on the repository type.
  84
  85 VCS subdirectory
  86 ^^^^^^^^^^^^^^^^
  87
  88 A field of this type is always optional because it defaults to empty, which
  89 corresponds to the root directory of the repository and is the same as
  90 specifying ``.`` explicitly.
  91
  92 Some projects put the sources for multiple packages inside a single VCS
  93 repository. This field lets you specify the relative path from the root of the
  94 repository to the top directory for the package, i.e. the directory containing
  95 the package's ``.cabal`` file.