PKGKDE-VCS(1)

🎀 PKGKDE-VCS(1) — the pkg-kde VCS helper 💖

okay bestie, welcome to pkgkde-vcs, the little helper from the Debian KDE packaging squad. this is the manual page, so grab a strawberry drink 🍓 and let's get into it.

---

✨ NAME ✨

pkgkde-vcs — a helper tool for Debian pkg-kde VCS repositories. no cap, that's literally what it is.

---

🌸 SYNOPSIS 🌸

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

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

---

🦋 DESCRIPTION 🦋

so pkgkde-vcs is a helper tool that's here to simplify a couple of routine tasks that come with packaging management in version control system (VCS) repositories. she transparently supports the VCSes used by the Debian Qt/KDE maintainer groups, wrapping up various VCS-related command sequences into a convenient CLI interface. but hear me out: this helper enforces the best practises and packaging conventions adopted by the Debian Qt/KDE maintainer groups, which means it should not be considered a general purpose packaging helper. she's niche, she's specialized, she's not for everybody, and that's the point 💅.

pkgkde-vcs should be run from the fully checked out packaging repository of the package it's supposed to act upon. first things first: it attempts to detect a VCS in use for the particular packaging in the working directory. ⚠️ heads up though — the detection might fail if the underlying VCS utilities are not installed. if you want to, or have to, force a specific VCS type, just 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 sets 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 a whole or are common for all VCSes it supports. they should be passed before the subcommand in order to be recognized. (order matters, bestie, she's picky 🫶)

even if pkgkde-vcs does extensive sanity checks before doing anything, an underlying command it executes might still fail. 😭 and then pkgkde-vcs will terminate immediately, possibly leaving the repository in an inconsistent state. it is up to a user to recover from such a failure. you've been warned, fr fr.

at the moment, pkgkde-vcs supports only Git VCS. that's it, that's the list.

---

⭐ OPTIONS ⭐

💜 Common options 💜

• -y — by default, execution of the first external command that makes changes to the repository has to be explicitly confirmed by the user. but if this option is specified, the first command will be run without confirmation. yes queen, no more y/n prompts.
• -n — do not run any external commands that make changes to the repository. super useful with -v to see what commands with what options would be run. like a dress rehearsal but for git 🎀.
• -v — be more verbose (e.g. show external commands as they are executed). she'll narrate her whole life to you.
• -- EXTERNAL TOOL OPTIONS — pass additional EXTERNAL TOOL OPTIONS to the external commands pkgkde-vcs executes to accomplish the task. see the 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 the 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.

the repository should be specified relatively to the root of the official pkg-kde repository tree. once the 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 the kde4libs repository from kde-sc, the akonadi repository from kde-req, and the 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 the current packaging state (HEAD) as an upload to the Debian archive. the repository working tree must be clean before executing this subcommand. current package version and target distribution are automatically determined from debian/changelog. the distribution must be a valid Debian suite in order to avoid tagging of unfinished (aka UNRELEASED) revisions. 💀 no tagging your half-finished situationship of a package.

the subcommand will create an annotated Git tag under the "debian/" namespace. the subcommand itself does not accept any additional options. all EXTERNAL TOOL OPTIONS (if specified) will be passed to the git tag invocation. it is recommended to sign tags by specifying -s option. ✨

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

• the tag will be 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 the ~ character in tag names.
• 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 to.

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:
  • 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.
  • 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> — the icon, the moment, the legend 🫶

---

okay that's the whole page bestie!! this was pkgkde-vcs version 0.15, dated 2012-05-27 — yes she's an elder millennial but she still slays 💅✨. now go forth and tag your packages responsibly, mwah 💜🦋🎀