Merge remote-tracking branch 'allan/working-split/vcs'

1 files changed, 40 insertions, 60 deletions

diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt
index 062b1ab6..47f9e884 100644
--- a/doc/PKGBUILD.5.txt
+++ b/doc/PKGBUILD.5.txt
@@ -47,6 +47,11 @@ similar to `$_basekernver`.
 *pkgver*::
 	The version of the software as released from the author (e.g., '2.7.1').
 	The variable is not allowed to contain colons or hyphens.
++
+The `pkgver` variable can be automatically updated by providing a `pkgver()` function
+in the PKGBUILD that outputs the new package version.  This is run after downloading
+and extracting the sources so can use those files in determining the new `pkgver`.
+This is most useful when used with sources from version control systems (see below).
 
 *pkgrel*::
 	This is the release number specific to the Arch Linux release. This
@@ -109,6 +114,10 @@ It is also possible to change the name of the downloaded file, which is helpful
 with weird URLs and for handling multiple source files with the same
 name. The syntax is: `source=('filename::url')`.
 +
+makepkg also supports building developmental versions of packages using sources
+downloaded from version control systems (VCS). For more information, see
+<<VCS,Using VCS Sources>> below.
++
 Files in the source array with extensions `.sig`, `.sign` or `.asc` are recognized by
 makepkg as PGP signatures and will be automatically used to verify the integrity
 of the corresponding source file.
@@ -392,69 +401,40 @@ The install script does not need to be specified in the source array. A
 template install file is available in '{pkgdatadir}' as 'proto.install' for
 reference with all of the available functions defined.
 
+Using VCS Sources[[VCS]]
+------------------------
+Building a developmental version of a package using sources from a version control
+system (VCS) is enabled by specifying the source in the form
+`source=('folder::url#fragment')`. Currently makepkg supports the `git`, `hg` and
+`svn` protocols.
 
-Development Directives
-----------------------
-makepkg supports building development versions of packages without having to
-manually update the pkgver in the PKGBUILD. This was formerly done using the
-separate utility 'versionpkg'. In order to utilize this functionality, your
-PKGBUILD must use correct variable names depending on the SCM being fetched
-from (e.g., 'makepkg-git', 'mplayer-svn').
-
-*CVS*::
-	The generated pkgver will be the date the package is built.
-
-	*_cvsroot*;;
-		The root of the CVS repository.
-
-	*_cvsmod*;;
-		The CVS module to fetch.
-
-*SVN*::
-	The generated pkgver will be the latest SVN revision number.
-
-	*_svntrunk*;;
-		The trunk of the SVN repository.
-
-	*_svnmod*;;
-		The SVN module to fetch.
-
-*Git*::
-	The generated pkgver will be the date the package is built.
-
-	*_gitroot*;;
-		The URL (all protocols supported) to the GIT repository.
+The source URL is divided into three components:
 
-	*_gitname*;;
-		GIT tag or branch to use.
-
-*Mercurial*::
-	The generated pkgver will be the hg tip revision number.
-
-	*_hgroot*;;
-		The URL of the mercurial repository.
-
-	*_hgrepo*;;
-		The repository to follow.
-
-*Darcs*::
-	The generated pkgver will be the date the package is built.
-
-	*_darcstrunk*;;
-		URL to the repository trunk.
-
-	*_darcsmod*;;
-		Darcs module to use.
-
-*Bazaar*::
-	The generated pkgver will be the latest Bazaar revision number (revno).
-
-	*_bzrtrunk*;;
-		URL to the bazaar repository.
-
-	*_bzrmod*;;
-		Bazaar module to use.
+*folder*::
+	(optional) Specifies an alternate folder name for makepkg to download the VCS
+	source into.
 
+*url*::
+	The url to the VCS repo. This must include the the vcs in the URL protocol for
+	makepkg to recognize this as a VCS source.  If the protocol does not include
+	the VCS name, it can be added by prefixing the URL with `vcs+`. For example,
+	using a git repository over `http` would have a source URL in the form
+	`git+http://...`.
+
+*fragment*::
+	(optional) Allows specifying a revision number or branch for makepkg to checkout
+	from the VCS. For example, to checkout a given revision, the source line would
+	have the format `source=(url#revision=123)`. The available fragments depends on
+	the VCS being used:
+
+	*git*;;
+		branch, commit, tag
+
+	*hg*;;
+		branch, revision, tag
+
+	*svn*;;
+		revision
 
 Example
 -------