Improved git-package.mk documentation.

[Roland Illig <roland.illig%gmx.de@localhost>]

Module Name:	pkgsrc-wip
Committed By:	Roland Illig <roland.illig%gmx.de@localhost>
Pushed By:	rillig
Date:		Sat Jan 6 20:48:31 2018 +0000
Changeset:	c498e94af4cd9e54799e6ecbef32a981eda546fd

Modified Files:
	mk/git-package.mk

Log Message:
Improved git-package.mk documentation.

To see a diff of this commit:
https://wip.pkgsrc.org/cgi-bin/gitweb.cgi?p=pkgsrc-wip.git;a=commitdiff;h=c498e94af4cd9e54799e6ecbef32a981eda546fd

Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.

diffstat:
 mk/git-package.mk | 31 +++++++++++++++++++++++++------
 1 file changed, 25 insertions(+), 6 deletions(-)

diffs:
diff --git a/mk/git-package.mk b/mk/git-package.mk
index df594be9b0..bcb71897e9 100644
--- a/mk/git-package.mk
+++ b/mk/git-package.mk
@@ -1,3 +1,5 @@
+# $NetBSD$
+#
 # This file provides simple access to git repositories, so that packages
 # can be created from git instead of from released tarballs.
 #
@@ -8,21 +10,38 @@
 #		GIT_REPO must be defined.
 #
 #	GIT_REPO.${id}
-#		The git repository
+#		The git repository.
+#
+#		Examples:
+#			https://github.com/NetBSD/pkgsrc
+#			git://git%github.com@localhost:NetBSD/pkgsrc.git
+#			git%github.com@localhost:NetBSD/pkgsrc.git
 #
 # It may define the following variables:
 #
 #	GIT_BRANCH.${id}
 #		The branch to check out.
 #
+#		This should seldomly be used since it prevents the build
+#		from being reproducible. Prefer a tag or a revision
+#		instead.
+#
 #	GIT_REVISION.${id}
 #		The revision to check out.
 #
+#		Example: 4b825dc642cb6eb9a060e54bf8d69288fbee4904
+#
 #	GIT_TAG.${id}
-#		Overridable GIT tag for a repository.
+#		The tag to check out.
+#
+#		Example: v1.0.0
 #
 #	GIT_ENV.${id}
-#		The environment for git, to set e.g. GIT_SSL_NO_VERIFY=true
+#		The environment variables for the git command.
+#
+#		Example: GIT_SSL_NO_VERIFY=true
+#
+# Keywords: git github
 
 .if !defined(_PKG_MK_GIT_PACKAGE_MK)
 _PKG_MK_GIT_PACKAGE_MK=	# defined
@@ -49,9 +68,9 @@ PKG_FAIL_REASON+=	"[git-package.mk] GIT_REPOSITORIES must be set."
 GIT_REPOSITORIES?=	# none
 .endif
 
-.for _repo_ in ${GIT_REPOSITORIES}
-.  if !defined(GIT_REPO.${_repo_})
-PKG_FAIL_REASON+=	"[git-package.mk] GIT_REPO."${_repo_:Q}" must be set."
+.for repo in ${GIT_REPOSITORIES}
+.  if !defined(GIT_REPO.${repo})
+PKG_FAIL_REASON+=	"[git-package.mk] GIT_REPO."${repo:Q}" must be set."
 .  endif
 .endfor