PKGKDE-VCS(1)						  Debian KDE packaging VCS helper					     PKGKDE-VCS(1)

NAME

       pkgkde-vcs - a helper tool for Debian pkg-kde VCS repositories.

SYNOPSIS

       pkgkde-vcs [-vy] subcommand [ SUBCOMMAND OPTIONS ] [ -- EXTERNAL TOOL OPTIONS ]

       pkgkde-git [-vy] subcommand [ SUBCOMMAND OPTIONS ] [ -- EXTERNAL TOOL OPTIONS ]

DESCRIPTION

       pkgkde-vcs is a helper tool which aims to simplify a couple of routine tasks associated with packaging management in version control system
       (VCS) repositories.  pkgkde-vcs transparently supports VCSes used by Debian Qt/KDE maintainer groups wrapping various VCS  related  command
       sequences  into	a  convenient CLI interface. Please note that this helper enforces the best practises and packaging conventions adopted by
       Debian Qt/KDE maintainer groups and therefore it should not be considered as a general purpose packaging helper.

       pkgkde-vcs should be run from the fully checked out packaging repository of the package it is supposed to act upon. Firstly, it attempts to
       detect  a  VCS  in  use for the particular packaging in the working directory. Please note, that the detection might fail if underlying VCS
       utilities are not installed. If you want or have to force a specific VCS type, run the command as pkgkde-$vcs, for example pkgkde-git.

       If detection is successful, pkgkde-vcs will perform tasks as defined for the specified subcommand (e.g. tag). Different set of  subcommands
       might  be  defined  for	each VCS and each of them might accept a different set of SUBCOMMAND OPTIONS (see below). All locally unrecognized
       subcommand options (or the ones specified as EXTERNAL TOOL OPTIONS after --) will be passed to the external VCS	tool(s)  which	pkgkde-vcs
       executes to do the job.

       pkgkde-vcs  accepts  a  couple of common options which apply to the helper as whole or are common for all VCSes it supports. They should be
       passed before subcommand in order to be recognized.

       Even if pkgkde-vcs does extensive sanity checks before doing anything, an underlying command it executes might still fail. Then	pkgkde-vcs
       will terminate immediately possibly leaving repository in an inconsistent state. It is up to a user to recover from such a failure.

       At the moment, pkgkde-vcs supports only Git VCS.

OPTIONS

   Common options
       -y     By  default,  execution  of  the first external command that makes changes to the repository has to be explicitly confirmed by user.
	      However, if this option is specified, the first command will be run without confirmation.

       -n     Do not run any external commands that make changes to the repository. Useful with -v to see what commands with what options would be
	      run.

       -v     Be more verbose (e.g. show external commands as they are executed).

       -- EXTERNAL TOOL OPTIONS
	      Pass additional EXTERNAL TOOL OPTIONS to the external commands pkgkde-vcs executes to accomplish the task. See documentations of the
	      specific subcommand for more details.

SUPPORTED VERSION CONTROL SYSTEMS AND SUBCOMMANDS

   Git
       In order to use pkgkde-vcs with Git, git(1) must be available in PATH.  Bare Git repositories are not supported and Git	repository  should
       be in the fully checked out state (except clone). The following subcommands for Git repositories are supported at the moment:

       clone  Clone  the  specified  pkg-kde git repository. This subcommand should be specified by forcing VCS to git, i.e. by running pkgkde-git
	      command rather than pkgkde-vcs.

	      Repository should be specified relatively to the root of the official pkg-kde repository	tree.  Once  operation	is  complete,  the
	      cloned  repository  will be put at the same relative location on the local filesystem and update-config (see below) will be executed
	      on it.

	      For example, in order to clone kde4libs repository from kde-sc, akonadi repository from kde-req and  pkg-kde-tools  repository  from
	      the root tree, execute:

	      $ pkgkde-git clone kde-sc/kde4libs

	      $ pkgkde-git clone kde-req/akonadi

	      $ pkgkde-git clone pkg-kde-tools

       tag    Tag  current packaging state (HEAD) as upload to Debian archive. Repository working tree must be clean before executing this subcom-
	      mand. Current package version and target distribution are automatically determined from debian/changelog.  Distribution  must  be  a
	      valid Debian suite in order to avoid tagging of unfinished (aka UNRELEASED) revisions.

	      The  subcommand  will  create  an  annotated Git tag under "debian/" namespace. The subcommand itself does not accept any additional
	      options. All EXTERNAL TOOL OPTIONS (if specified) and will be passed to git tag invocation. It is recommended to sign tags by speci-
	      fying -s option.

	      The tag created by pkgkde-vcs tag will meet the following requirements:

	      o      The  tag  will named as "debian/<version>" where <version> is a full debian package version without epoch. All occurrences of
		     the ~ character in <version> will be replaced with the - character because Git does not support ~ character in tag names.

	      o      The tag will be assigned the message with content like <version>/<distribution>" where <version> is a full debian version	of
		     the package (without any modifications including epoch) and <distribution> is the distribution this package is uploaded.

	      For  example, a standard pkgkde-vcs tag will execute the following under the hood (assuming version is 1:2.3.4-5 and distribution is
	      experimental):

		     $ git tag debian/2.3.4-5 -m "1:2.3.4-5/experimental"

       update-config
	      Do some common configuration on the checked out packaging repository. At the moment, the subcommand performs the following:

	      o      Set up master branch and debian tags for pushing. -f option may be specified to force update  of  the  pushing  configuration
		     even if some pushing configuration already exists.

	      o      Set  repository user name and email address to the values of the DEBFULLNAME and DEBEMAIL environment variables respectively.
		     -f option may be specified to override the values even if the repository has some specified already.

LICENSE

       This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as  published	by
       the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

AUTHORS

       Modestas Vainius <modax@debian.org>

0.15								    2012-05-27							     PKGKDE-VCS(1)