rpkg(1)

📦
version 3.3 · 2 versions
, in fedora 43

💖 rpkg(1) 💖

okay so bestie, welcome to the rpm-packager manual — this is THE page for rpkg, and honestly? it's a lot. buckle up, we're doing this together 🫶

✨ NAME ✨

rpkg — RPM packaging utility 💅

🌸 SYNOPSIS 🌸

rpkg [ global_options ] command [ command_options ] [ command_arguments ]
rpkg help
rpkg command --help

🎀 DESCRIPTION 🎀

So like, rpkg is a script that manages spec enriched Git repositories — meaning any repo that has an rpm spec file in it. That's the whole vibe. 💫

It's built to work with expanded application sources and with standard DistGit tarballs and patches. Both. It's versatile like that, periodt.

⚠️ ok listen, this part matters: you should trust the .spec files you work with. Because a bunch of operations (like rpkg srpm or rpkg lint) involve parsing the spec file, and parsing the spec file brings along evaluation of any shell or lua scriplets present in it. no cap, fr fr. only point it at specs you actually trust. 💀

💅 Global Options 💅

(this section is empty on the page — nothing here yet, bestie, we move)

🔥 COMMAND OVERVIEW 🔥

here's the whole menu, like a little ✨command tasting flight✨:

  • rpkg add [-h] [--all] [paths ...] — Add changes to index
  • rpkg build [-h] [--outdir OUTDIR] [--spec SPEC] [--config CONFIG] [--wait] [project] — Alias for copr-build
  • rpkg ci [-h] [--message MESSAGE | --file FILE] [--all] [--amend] [--with-changelog] [--tag] [--push] [--signoff] [file ...] — Alias for commit
  • rpkg clean [-h] [--dry-run] [-x] [--force] [-d] — Remove untracked files
  • rpkg clog [-h] [--raw] — Output top changelog entry to stdout
  • rpkg clone [-h] [--branches] [--branch BRANCH] [--anonymous] repo_path [directory] — Clone and checkout a repository
  • rpkg commit [-h] [--message MESSAGE | --file FILE] [--all] [--amend] [--with-changelog] [--tag] [--push] [--signoff] [file ...] — Commit changes
  • rpkg compile [-h] [--target TARGET] [--with OPTION] [--without OPTION] [--outdir OUTDIR] [--spec SPEC] [--short-circuit SHORT_CIRCUIT] [--nocheck] — Local test rpmbuild compile
  • rpkg config [-h] — Do nothing, only output used config
  • rpkg copr-build [-h] [--outdir OUTDIR] [--spec SPEC] [--config CONFIG] [--wait] [project] — Build package in Copr build system
  • rpkg diff [-h] [--cached] [file ...] — Show changes between the last commit and working tree, etc.
  • rpkg gimmespec [-h] — Print auto-located input spec file name
  • rpkg import [-h] [--repo-path REPO_PATH] [--skip-diffs] [--offline] srpm — Import srpm content
  • rpkg install [-h] [--target TARGET] [--with OPTION] [--without OPTION] [--outdir OUTDIR] [--spec SPEC] [--short-circuit SHORT_CIRCUIT] [--nocheck] — Local test rpmbuild install
  • rpkg lint [-h] [--info] [--rpmlint-config RPMLINT_CONFIG] [target_path] — Run rpmlint against rendered spec and build products if present. Needs rpmlint to be installed.
  • rpkg local [-h] [--target TARGET] [--with OPTION] [--without OPTION] [--outdir OUTDIR] [--spec SPEC] [--nocheck] — Local test rpmbuild binary
  • rpkg log [-h] [--graph] [--all] [--show-signature] [revision ...] [path ...] — Display git log history
  • rpkg merge [-h] [--no-commit] [--squash] [--message MESSAGE] [--file FILE] [--signoff] [--abort] [--continue] [commit ...] — Incorporates changes from the named commits into the current branch
  • rpkg new [-h] [--outdir OUTDIR] [--spec SPEC] — Diff against last package tag
  • rpkg nvr [-h] [--outdir OUTDIR] [--spec SPEC] — Print package name-version-release
  • rpkg prep [-h] [--target TARGET] [--with OPTION] [--without OPTION] [--outdir OUTDIR] [--spec SPEC] — Prep test rpmbuild binary
  • rpkg pull [-h] [--rebase] [--no-rebase] — Pull changes from the remote repository and update the working copy
  • rpkg push [-h] [--follow-tags] [--force] — Push changes and annotated tags to remote repository
  • rpkg reset [-h] [--soft | --mixed | --hard] [commit|path] — Reset branch tip, index, or the working tree
  • rpkg sources [-h] [--repo-path REPO_PATH] [--outdir OUTDIR] — Download source files from lookaside cache
  • rpkg spec [-h] [--outdir OUTDIR] [--spec SPEC] [--sources] [--print] — Generate spec file from a spec template
  • rpkg srpm [-h] [--target TARGET] [--with OPTION] [--without OPTION] [--outdir OUTDIR] [--spec SPEC] — Create a source rpm
  • rpkg status [-h] [pathspec ...] — Display git status of the current working tree and index
  • rpkg switch [-h] [--create] [--detach] [--list-branches] [--fetch] [target] — Work with branches
  • rpkg tag [-h] [--list] [--delete] [--skip-edit] [--name NAME] [--version VERSION] [--release RELEASE] [tag] — Manage git tags
  • rpkg unused-patches [-h] — Print list of patches in CWD not referenced by name in the specfile
  • rpkg upload [-h] [--repo-path REPO_PATH] [--offline] file [file ...] — Upload source files
  • rpkg verify-files [-h] [target_dir] — Locally verify %%files section

👑 COMMAND REFERENCE 👑

🌈 rpkg add

usage: rpkg add [-h] [--all] [paths ...]

This command updates the index with changes found in the working tree. cute, simple, iconic. ✨

positional arguments

  • paths — Specific paths to add changes for.

options

  • -h, --help — show this help message and exit
  • --all, -A — Update index with all changes found in the working tree.

🌈 rpkg build

usage: rpkg build [-h] [--outdir OUTDIR] [--spec SPEC] [--config CONFIG]
                  [--wait]
                  [project]

Build package in Copr build system. To do this you need to have copr-cli installed and also have your Copr API key set up. For more info about the API key, see the API KEY section in the copr-cli(1) man page. 🔑

🚨 NOTE, and this is a big one: this method of building the package does not support with, without, and rpmdefines rpkg configuration options. These options are used to build an srpm, and that srpm is then sent to Copr — but the rpm build in Copr happens without these options already, which is important for the resulting build. If you want these options applied, you should instead setup auto-rebuilding in Copr that reacts to new pushes into your repository. iykyk 💅

positional arguments

  • project — Name of the project in format OWNER/PROJECT. You can omit it if you have specified the copr_project configuration option.

options

  • -h, --help — show this help message and exit
  • --outdir OUTDIR — Where to put any generated rpm content. Directory must exist.
  • --spec SPEC — An input spec template. If not given, the spec template is auto-located in <path> as a file ending either with .spec.rpkg or .spec suffix (in this order). The directory of the template then also becomes search location for the associated sources and rpkg.conf file. By default, these files are being looked up in <path>. Essentially, this argument changes the subpackage we work with and which is determined by the --path argument initially (with CWD as the default value for it).
  • --config CONFIG — Path to an alternative Copr configuration file
  • --wait, -w — Wait for build to finish.

🌈 rpkg ci

usage: rpkg ci [-h] [--message MESSAGE | --file FILE] [--all] [--amend]
               [--with-changelog] [--tag] [--push] [--signoff]
               [file ...]

Alias for commit. same energy, shorter name. 💫

positional arguments

  • file — Optional list of specific files to commit

options

  • -h, --help — show this help message and exit
  • --message, -m MESSAGE — Use the given <msg> as the commit message summary
  • --file, -F FILE — Take the commit message from the given file
  • --all, -a — Tell the command to automatically stage files that have been modified or deleted.
  • --amend — Replace the tip of the current branch by creating a new commit.
  • --with-changelog — Get the last changelog from SPEC as commit message content. This option must be used with -m together.
  • --tag, -t — Create a tag for this commit
  • --push, -p — Commit and push as one action
  • --signoff, -s — Include a signed-off-by

🌈 rpkg clean

usage: rpkg clean [-h] [--dry-run] [-x] [--force] [-d]

This command can be used to clean up your work tree from untracked files and, additionally if the -x option is passed, files described by .gitignore. 🧹✨

options

  • -h, --help — show this help message and exit
  • --dry-run, -n — Don't actually remove anything, just show what would be done.
  • -x — Don't exclude files described by .gitignore rules from deletion.
  • --force, -f — This option is required to perform deletion of any files or directories if git configuration variable clean.requireForce is set to true. It is passed by default if rpkg configuration variable git.clean_force is set to true.
  • -d — Remove whole directories in addition to files. This option is passed by default if rpkg configuration variable git.clean_dirs is set to true.

🌈 rpkg clog

usage: rpkg clog [-h] [--raw]

This will output the latest rpm changelog entry to stdout. The leading "- " text will be stripped. 🎀

options

  • -h, --help — show this help message and exit
  • --raw — Generate a more "raw" clog without twiddling the contents

🌈 rpkg clone

usage: rpkg clone [-h] [--branches] [--branch BRANCH] [--anonymous]
                  repo_path [directory]

This command will clone the named repository from the configured repository base URL. By default it will also checkout the master branch for your working copy. 🌱

positional arguments

  • repo_path — Name of the repository to clone or full clone url. If just a basename is specified, preconfigured git clone urls and default namespace is used to construct the final clone url.
  • directory — Directory in which to clone the repository

options

  • -h, --help — show this help message and exit
  • --branches, -B — Checkout a subdirectory for each branch
  • --branch, -b BRANCH — Check out a specific branch. This has no effect if --branches/-B is specified.
  • --anonymous, -a — Check out a repository anonymously

🌸 rpkg commit 🌸

rpkg commit [-h] [--message MESSAGE | --file FILE] [--all] [--amend]
            [--with-changelog] [--tag] [--push] [--signoff]
            [file ...]

okay bestie this one literally just calls git commit for you 💅 every tracked file that's got changes gets committed — unless you hand it a specific file list, in which case only those get the treatment. $EDITOR pops open so you can write your changelog message, unless you already gave the command one. And yes you can tag and/or push in the same breath, no extra steps. Oh and if you've set the git.gpg_keyid rpkg configuration option, then the commit and the tag get created signed with that GPG key you configured. iconic behavior honestly.

positional arguments:

  • file — optional list of specific files to commit, if you're feeling picky

options:

  • -h, --help — shows this help message and dips
  • --message, -m MESSAGE — use the given <msg> as the commit message summary
  • --file, -F FILE — steal the commit message from the file you point at
  • --all, -a — tells the command to automatically stage files that have been modified or deleted
  • --amend — replaces the tip of the current branch by creating a new commit
  • --with-changelog — grabs the last changelog from the SPEC and uses it as the commit message content. ⚠️ this one must be used together with -m
  • --tag, -t — create a tag for this commit
  • --push, -p — commit and push as one single action, multitasking queen
  • --signoff, -s — include a signed-off-by

✨ rpkg compile ✨

rpkg compile [-h] [--target TARGET] [--with OPTION] [--without OPTION]
             [--outdir OUTDIR] [--spec SPEC]
             [--short-circuit SHORT_CIRCUIT] [--nocheck]

this one rings up rpmbuild to compile the source. by default the prep and configure stages happen too, unless you hit it with the short-circuit option 🫶

options:

  • -h, --help — shows this help message and exits
  • --target TARGET — prep for a specific arch or arch-vendor-os
  • --with OPTION — enable %bcond spec OPTION. can be specified multiple times, stack 'em
  • --without OPTION — disable %bcond spec OPTION. also stackable, multiple times
  • --outdir OUTDIR — where to put any generated rpm content. the directory must exist
  • --spec SPEC — an input spec template. if you don't give one, the spec template is auto-located in <path> as a file ending either with .spec.rpkg or .spec suffix (in this order). the directory of the template then also becomes the search location for the associated sources and rpkg.conf file. by default, these files are being looked up in <path>. essentially, this argument changes the subpackage we work with, and which one that is gets determined by the --path argument initially (with CWD as the default value for it)
  • --short-circuit SHORT_CIRCUIT — short-circuit compile
  • --nocheck — nocheck compile

🎀 rpkg config 🎀

rpkg config [-h]

do nothing. literally nothing. only output the config that's being used. it's giving "I'm just here to vibe" 💀

options:

  • -h, --help — shows this help message and exits

👑 rpkg copr-build 👑

rpkg copr-build [-h] [--outdir OUTDIR] [--spec SPEC] [--config CONFIG]
                [--wait]
                [project]

build the package in the Copr build system, bestie.

you need to have copr-cli installed and also have your Copr API key set up. for more info about the API key, go look at the API KEY section in the copr-cli(1) man page.

NOTE: this method of building the package does not support the with, without, and rpmdefines rpkg configuration options. those options are used to build an srpm which is then sent to Copr — but the rpm build in Copr happens without these options already, which is important for the resulting build. so if you want these options applied, you should rather set up auto-rebuilding in Copr that will react to new pushes into your repository. no cap.

positional arguments:

  • project — name of the project in the format OWNER/PROJECT. you can omit it if you've specified the copr_project configuration option

options:

  • -h, --help — shows this help message and exits
  • --outdir OUTDIR — where to put any generated rpm content. the directory must exist
  • --spec SPEC — an input spec template. if you don't give one, the spec template is auto-located in <path> as a file ending either with .spec.rpkg or .spec suffix (in this order). the directory of the template then also becomes search location for the associated sources and rpkg.conf file. by default, these files are being looked up in <path>. essentially, this argument changes the subpackage we work with, and which one that is gets determined by the --path argument initially (with CWD as the default value for it)
  • --config CONFIG — path to an alternative Copr configuration file
  • --wait, -w — wait for the build to finish (patience era 🙈)

🦋 rpkg diff 🦋

rpkg diff [-h] [--cached] [file ...]

uses git diff to show the changes that have been made to tracked files. by default, cached changes — the ones you've already git added — will not show up.

positional arguments:

  • file — optionally diff specific files

options:

  • -h, --help — shows this help message and exits
  • --cached — view staged changes

⭐ rpkg gimmespec ⭐

rpkg gimmespec [-h]

prints the auto-located input spec file name. that's it. that's the whole personality 🌈

options:

  • -h, --help — shows this help message and exits

💖 rpkg import 💖

rpkg import [-h] [--repo-path REPO_PATH] [--skip-diffs] [--offline]
            srpm

this extracts sources, patches, and the spec file from an srpm and overwrites the current package content accordingly. it imports to the current branch by default. newly discovered sources get uploaded and .gitignore and the sources file get updated accordingly. very "new year new me" of it.

positional arguments:

  • srpm — source rpm to import. it can also be an URL, in which case the target srpm will be downloaded first

options:

  • -h, --help — shows this help message and exits
  • --repo-path REPO_PATH — path to the git repository for which to upload sources. if not specified, it will be automatically derived from the remote URL configured for the current branch
  • --skip-diffs — don't show diffs when importing
  • --offline — do not actually upload the files, but do all the rest

🧚 rpkg install 🧚

rpkg install [-h] [--target TARGET] [--with OPTION] [--without OPTION]
             [--outdir OUTDIR] [--spec SPEC]
             [--short-circuit SHORT_CIRCUIT] [--nocheck]

this calls rpmbuild to run the install section. all the leading sections get processed as well, unless you use the short-circuit option ✨

options:

  • -h, --help — shows this help message and exits
  • --target TARGET — prep for a specific arch or arch-vendor-os
  • --with OPTION — enable %bcond spec OPTION. can be specified multiple times
  • --without OPTION — disable %bcond spec OPTION. can be specified multiple times
  • --outdir OUTDIR — where to put any generated rpm content. the directory must exist
  • --spec SPEC — an input spec template. if you don't give one, the spec template is auto-located in <path> as a file ending either with .spec.rpkg or .spec suffix (in this order). the directory of the template then also becomes search location for the associated sources and rpkg.conf file. by default, these files are being looked up in <path>. essentially, this argument changes the subpackage we work with, and which one that is gets determined by the --path argument initially (with CWD as the default value for it)
  • --short-circuit SHORT_CIRCUIT — short-circuit install
  • --nocheck — nocheck install

💅 rpkg lint 💅

rpkg lint [-h] [--info] [--rpmlint-config RPMLINT_CONFIG] [target_path]

Rpmlint can be configured using the --rpmlint-config/-r option, or by setting the rpkg.rpmlint_config variable. pick your fighter 🎀

positional arguments:

  • target_path — directory with rpm items to be linted, or just a single rpm item like a .spec file. if not specified, the latest package directory from the base output path will be selected

options:

  • -h, --help — shows this help message and exits
  • --info, -i — display explanations for reported messages
  • --rpmlint-config, -r RPMLINT_CONFIG — use a specific configuration file for rpmlint

🔥 rpkg local 🔥

rpkg local [-h] [--target TARGET] [--with OPTION] [--without OPTION]
           [--outdir OUTDIR] [--spec SPEC] [--nocheck]

locally test run of rpmbuild producing binary RPMs. main character energy, but make it local 🫶

options:

  • -h, --help — shows this help message and exits
  • --target TARGET — prep for a specific arch or arch-vendor-os
  • --with OPTION — enable %bcond spec OPTION. can be specified multiple times
  • --without OPTION — disable %bcond spec OPTION. can be specified multiple times
  • --outdir OUTDIR — where to put any generated rpm content. the directory must exist
  • --spec SPEC — an input spec template. if you don't give one, the spec template is auto-located in <path> as a file ending either with .spec.rpkg or .spec suffix (in this order). the directory of the template then also becomes search location for the associated sources and rpkg.conf file. by default, these files are being looked up in <path>. essentially, this argument changes the subpackage we work with, and which one that is gets determined by the --path argument initially (with CWD as the default value for it)
  • --nocheck — nocheck build
  • -h, --help — shows this help message and dips, no notes 💅
  • --target TARGET — preps for a specific arch or arch-vendor-os.
  • --with OPTION — enables the %bcond spec OPTION. You can stack this one, specify it multiple times, go off bestie 🌸
  • --without OPTION — disables the %bcond spec OPTION. Also stackable, also multiple times ✨
  • --outdir OUTDIR — where to put any generated rpm content. The directory has to already exist, it will not make it for you 😭
  • --spec SPEC — an input spec template. If you don't hand it one, the spec template gets auto-located in <path> as a file ending either with .spec.rpkg or .spec suffix (in this order). The directory of the template then also becomes the search location for the associated sources and rpkg.conf file. By default, these files are being looked up in <path>. Basically: this argument changes the subpackage we work with, and which one that is gets determined by the --path argument initially (with CWD as the default value for it). Very demure, very mindfull 💖
  • --nocheck — nocheck local build 🫶

🌈 rpkg log

usage: rpkg log [-h] [--graph] [--all] [--show-signature]
                [revision ...] [path ...]

Displays the git log history, bestie. It can be configured by the git.log_graph and git.log_all rpkg configuration options 👑

positional arguments

  • revision — specific revisions or revision range to be shown.
  • path — limits commits to those that touch the specific path(s). You might need to use a -- to explicitly separate paths from revisions. And in that case, you also need to insert another -- to first separate options from all the positional arguments. Yes, two of them. Not me explaining this twice 🙈

options

  • -h, --help — show this help message and exit.
  • --graph — draws a text-based graphical representation of the commit history. By default enabled by the rpkg configuration option git.log_graph ✨
  • --all — pretends as if all the refs in refs/, along with HEAD, are listed on the command line as a revision. By default enabled by the rpkg configuration option git.log_all.
  • --show-signature — show gpg signatures and check their validity 🔐

🦋 rpkg merge

usage: rpkg merge [-h] [--no-commit] [--squash] [--message MESSAGE]
                  [--file FILE] [--signoff] [--abort] [--continue]
                  [commit ...]

Incorporates changes from the named commits (since the time their histories diverged from the current branch) into the current branch. Classic merge behaviour, no cap 🫶

positional arguments

  • commit — commits, usually other branch heads, to merge into our branch. If no commit is given, merge the remote-tracking branches that the current branch is configured to use as its upstream.

options

  • -h, --help — show this help message and exit.
  • --no-commit — performs the merge but does not auto-commit.
  • --squash — produces the working tree and index state as if a real merge happened but does not auto-commit. The next commit will have only a single parent and contain all the merged changes. Squash it, slay it 💅
  • --message, -m MESSAGE — use the given <msg> as the commit message summary.
  • --file, -F FILE — take the commit message from the given file.
  • --signoff — add a Signed-off-by line by the committer ✍️
  • --abort — abort the current conflict resolution process, and try to reconstruct the pre-merge state. The escape hatch, we love her 🙏
  • --continue — when all your merge conflicts have been resolved, you can conclude the merge by running this command.

🎀 rpkg new

usage: rpkg new [-h] [--outdir OUTDIR] [--spec SPEC]

This will use git to show a diff of all the changes (even uncommitted changes) since the last package tag was created. The receipts, literally 📸

options

  • -h, --help — show this help message and exit.
  • --outdir OUTDIR — where to put any generated rpm content. The directory must exist.
  • --spec SPEC — an input spec template. If not given, the spec template is auto-located in <path> as a file ending either with .spec.rpkg or .spec suffix (in this order). The directory of the template then also becomes search location for the associated sources and rpkg.conf file. By default, these files are being looked up in <path>. Essentially, this argument changes the subpackage we work with and which is determined by the --path argument initially (with CWD as the default value for it) 💖

⭐ rpkg nvr

usage: rpkg nvr [-h] [--outdir OUTDIR] [--spec SPEC]

Print package name-version-release. That's it, that's the whole vibe 🏷️

options

  • -h, --help — show this help message and exit.
  • --outdir OUTDIR — where to put any generated rpm content. Directory must exist.
  • --spec SPEC — an input spec template. If not given, the spec template is auto-located in <path> as a file ending either with .spec.rpkg or .spec suffix (in this order). The directory of the template then also becomes search location for the associated sources and rpkg.conf file. By default, these files are being looked up in <path>. Essentially, this argument changes the subpackage we work with and which is determined by the --path argument initially (with CWD as the default value for it) ✨

🌸 rpkg prep

usage: rpkg prep [-h] [--target TARGET] [--with OPTION] [--without OPTION]
                 [--outdir OUTDIR] [--spec SPEC]

Use rpmbuild to "prep" the sources — that means unpack the source archive(s) and apply any patches 🧰

options

  • -h, --help — show this help message and exit.
  • --target TARGET — prep for a specific arch or arch-vendor-os.
  • --with OPTION — enable %bcond spec OPTION. Can be specified multiple times.
  • --without OPTION — disable %bcond spec OPTION. Can be specified multiple times.
  • --outdir OUTDIR — where to put any generated rpm content. Directory must exist.
  • --spec SPEC — an input spec template. If not given, the spec template is auto-located in <path> as a file ending either with .spec.rpkg or .spec suffix (in this order). The directory of the template then also becomes search location for the associated sources and rpkg.conf file. By default, these files are being looked up in <path>. Essentially, this argument changes the subpackage we work with and which is determined by the --path argument initially (with CWD as the default value for it) 💜

🧚 rpkg pull

usage: rpkg pull [-h] [--rebase] [--no-rebase]

This command uses git to fetch remote changes and apply them to the current working copy. A rebase option is available which can be used to avoid merges 👑

options

  • -h, --help — show this help message and exit.
  • --rebase — rebase the locally committed changes on top of the remote changes after fetching. This can avoid a merge commit, but does rewrite local history 😭
  • --no-rebase — do not rebase, overriding .git settings to the contrary.

🔥 rpkg push

usage: rpkg push [-h] [--follow-tags] [--force]

Push changes and annotated tags to remote repository. Send it 📤

options

  • -h, --help — show this help message and exit.
  • --follow-tags — push all the refs that would be pushed without this option and also push annotated tags reachable from the refs that are pushed by default. This option is passed by default if the git.push_follow_tags configuration variable is set to true ✨
  • --force, -f — force push. Careful bestie, this one rewrites what's out there.

💀 rpkg reset

usage: rpkg reset [-h] [--soft | --mixed | --hard] [commit|path]

Reset HEAD to the specified commit and update index and/or working tree. Alternatively, if path is passed instead of commit, reset the respective index entry to its state at HEAD 🔄

positional arguments

  • commit|path — commit or path. If path is passed, the respective index entry is updated to its HEAD state, otherwise the action depends on the specified option switch (--mixed is implicit).

options

  • -h, --help — show this help message and exit.
  • --soft — does not touch the index file or the working tree. Only resets the head to the specified commit.
  • --mixed — resets the index but not the working tree. This is the default action.
  • --hard — resets the index and working tree. Any changes to tracked files in the working tree since the specified commit are discarded. Gone. Poof. 🙈

🍓 rpkg sources

usage: rpkg sources [-h] [--repo-path REPO_PATH] [--outdir OUTDIR]

Download source files from lookaside cache. Grab the goods 🛍️

options

  • -h, --help — show this help message and exit.
  • --repo-path REPO_PATH — path to git repository for which to download sources. If not specified, it will be automatically derived from remote URL configured for the current branch.
  • --outdir OUTDIR — directory to put downloaded files into (defaults to cwd).

💜 rpkg spec

usage: rpkg spec [-h] [--outdir OUTDIR] [--spec SPEC] [--sources] [--print]

Preprocess a given spec template and put the resulting spec file into outdir.

The spec template is simply copied into the outdir if spec preprocessing is turned off, or if the input spec template does not contain any preprocessor macros. Like, it's just a copy-paste at that point. No glow-up needed. 💅

✨ options ✨

  • -h, --help — show this help message and exit. Your classic escape hatch. 🫶
  • --outdir OUTDIR — Where to put any generated rpm content. The directory must exist. It will not be created for you, bestie, it is not that kind of girl.
  • --spec SPEC — An input spec template. If not given, the spec template is auto-located in <path> as a file ending either with .spec.rpkg or .spec suffix — and yes, in that order. The directory of the template then also becomes the search location for the associated sources and rpkg.conf file. By default, these files are being looked up in <path>. Essentially, this argument changes the subpackage we work with, which is determined by the --path argument initially (with CWD as the default value for it). So it's giving "actually, we're working over here now". 💁‍♀️
  • --sources — Enable source generation by the input spec template. By default disabled. You gotta opt in, no cap.
  • --print, -p — Print the rendered spec file to stdout. Iconic for peeking at what you cooked. 👀

🌈 rpkg srpm 🌈

usage: rpkg srpm [-h] [--target TARGET] [--with OPTION] [--without OPTION]
                 [--outdir OUTDIR] [--spec SPEC]

Create a source rpm. That's it, that's the whole vibe. ✨

✨ options ✨

  • -h, --help — show this help message and exit.
  • --target TARGET — Prep for a specific arch or arch-vendor-os.
  • --with OPTION — Enable %bcond spec OPTION. Can be specified multiple times. Stack 'em up, queen. 👑
  • --without OPTION — Disable %bcond spec OPTION. Can be specified multiple times.
  • --outdir OUTDIR — Where to put any generated rpm content. Directory must exist. Same energy as before, it's not gonna build the folder for you.
  • --spec SPEC — An input spec template. If not given, the spec template is auto-located in <path> as a file ending either with .spec.rpkg or .spec suffix (in this order). The directory of the template then also becomes the search location for the associated sources and rpkg.conf file. By default, these files are being looked up in <path>. Essentially, this argument changes the subpackage we work with, and which is determined by the --path argument initially (with CWD as the default value for it).

🦋 rpkg status 🦋

usage: rpkg status [-h] [pathspec ...]

Display git status of the current working tree and index. The mirror moment, but for your repo. 🪞

✨ positional arguments ✨

  • pathspec — Limit status information to the specific subpaths. Narrow it down, focus your lens. 🔍

✨ options ✨

  • -h, --help — show this help message and exit.

💜 rpkg switch 💜

usage: rpkg switch [-h] [--create] [--detach] [--list-branches] [--fetch]
                   [target]

Switch to a given git branch. If the --detach option is given, also tag, or a commit can be used as a target for switching. Additionally, this command can be used to list the existing local and remote branches, or to fetch new refs from remote. Multitasking queen fr fr. 👑

✨ positional arguments ✨

  • target — Target branch name or, alternatively, commit or tag to switch to. If provided with a remote branch name that does not have a local match, it creates one and sets it to track the corresponding remote branch. So it just ✨makes✨ the local branch for you. So generous.

✨ options ✨

  • -h, --help — show this help message and exit.
  • --create, -c — Create a new local branch even if it does not have the corresponding remote, and switch to it. Going off the grid, love that for you. 🧚
  • --detach, -d — Detach HEAD at target commit or tag.
  • --list-branches, -l — List both remote-tracking branches and local branches. Implied when target is not specified. So if you pass nothing, you get the list anyway. Sneaky but helpful.
  • --fetch — Fetch branches and tags from remote before switch.

🎀 rpkg tag 🎀

usage: rpkg tag [-h] [--list] [--delete] [--skip-edit] [--name NAME]
                [--version VERSION] [--release RELEASE]
                [tag]

This command uses git to create, list, or delete tags. If you have set git.gpg_keyid in rpkg configuraion, the tags will be created signed. Signed tags?? Secure AND cute, we love to see it. 🔐✨

✨ positional arguments ✨

  • tag — Name of the tag. Overrides any of the --name, --version, --release args if specified. It said "I'm the main character now." 💅

✨ options ✨

  • -h, --help — show this help message and exit.
  • --list, -l — List all tags with a given pattern, or all if no pattern is given.
  • --delete, -d — Delete a tag. Gone. Poof. Make sure you mean it. 💀
  • --skip-edit, -s — Skip changelog editing when creating a tag.
  • --name, -n NAME — Set the package name part of the tag name to a specific value.
  • --version, -v VERSION — Set the version part of the tag name to a specific value.
  • --release, -r RELEASE — Set the release part of the tag name to a specific value.

🌸 rpkg unused-patches 🌸

usage: rpkg unused-patches [-h]

Print list of patches in the current working directory not referenced by name in the specfile. The callout post for your forgotten patches. 😭

✨ options ✨

  • -h, --help — show this help message and exit.

⭐ rpkg upload ⭐

usage: rpkg upload [-h] [--repo-path REPO_PATH] [--offline] file [file ...]

This command will upload new source file(s) to the lookaside cache. Source file names are appended to the sources file, and .gitignore will be also updated with the new uploaded file(s). Please remember to commit them. Not me reminding you twice because you will forget. 🙈

✨ positional arguments ✨

  • file — List of files to upload.

✨ options ✨

  • -h, --help — show this help message and exit.
  • --repo-path REPO_PATH — Path to git repository for which to upload sources. If not specified, it will be automatically derived from the remote URL configured for the current branch. Auto-detect mode, slay.
  • --offline — Do not actually upload the files, but do all the rest, which involves updating .gitignore and the sources file. A little dry run moment. 🫶

💖 rpkg verify-files 💖

usage: rpkg verify-files [-h] [target_dir]

Locally run rpmbuild -bl to verify the spec file's %files sections. This requires a successful run of the install commaned in advance. So like, do the install step first or this does nothing for you. 😭

✨ positional arguments ✨

  • target_dir — Directory with build results to verify. If not specified, the latest package directory from the base output path will be selected. It'll pick the freshest one for you. 🍓

✨ options ✨

  • -h, --help — show this help message and exit.

💖 CONFIGURATION 💖

okay bestie, this is the part where rpkg goes snooping through your config files, and it has a very specific order it reads them in. no skipping, no vibes-based priority, just this list:

/etc/rpkg.conf, ~/.config/rpkg.conf, <git_root>/rpkg.conf, <pkg_path>/rpkg.conf

here's the tea on who wins: config in <pkg_path>/rpkg.conf has the highest priority, and config in /etc/rpkg.conf has the lowest priority. main character vs. background extra, fr.

so what even is <git_root>? it's the top level of the Git repo you're currently hanging out in. and here's the plot twist: if you're in a plain directory (like, there's no .git subdir) and all your parent directories are also plain, then rpkg just skips reading <git_root>/rpkg.conf entirely. ghosted.

and <pkg_path>? that's your CWD by default, but you can override it with the --path argument or the --spec argument — and --spec wins that fight, it has higher priority. 💅

there are also built-in default values for every single variable, used whenever a variable isn't specified in any config file. they're all listed below with their descriptions, so you literally cannot miss them.

✨ DEFAULT CONFIGURATION WITH DESCRIPTIONS ✨

this is the whole thing, verbatim, no cap:

[rpkg]
# Whether to enable spec preprocessing,
# that is parsing and evaluation of {{{ ... }}} expressions
# type: bool
preprocess_spec = True

# Base directory where generated files should be put.
# The files will not be put directly there but
# instead into dynamically generated subdirectories
# type: string
base_output_path = /tmp/rpkg

# Path to user preproc macros. You may use ${git_props:root}
# variable to anchor the path to top-level of your git repo.
# type: list of space-separated strings
user_macros =

# rpm bcondition "with" specifier
# type: list of space-separated strings
with =

# rpm bcondition "without" specifier
# type: list of space-separated strings
without =

# Defines rpm variables for spec parsing
# type: list of space-separated quoted string pairs (e.g. 'dist %nil')
rpmdefines =

# Defines rpm variables for spec parsing during
# version/release bumping (see the tag subcommand)
# This list is not being concatenated with rpmdefines.
# type: list of space-separated quoted string pairs
bump_rpmdefines = 'dist %nil'

# Path to rpmlint configuration (see the lint subcommand)
# type: string
rpmlint_config =

# Paths to default preproc macros relative to
# /usr/lib/rpkg.macros.d directory
# type: list of space-separated strings
default_macros = git.bash

[git]
# Default Git repository URL, used by `rpkg clone <repo_path>`
# type: string
clone_url =

# Default Git repository URL, used by `rpkg clone -a <repo_path>`
# type: string
anon_clone_url =

# If you clone a project with rpkg clone and specify only
# its basename (i.e. the last part like "dist-git"), then
# default namespace (e.g. rpms) will be automatically
# prepended to it together with ending slash if specified.
# type: string
default_namespace =

# Whether to automatically push tags with rpkg push
# type: bool
push_follow_tags = True

# Allows removing of files and directories
# for rpkg clean operation
# type: bool
clean_force = True

# Whether rpkg clean should descend into
# untracked directories
# type: bool
clean_dirs = True

# Whether rpkg log should be in graph form
# type: bool
log_graph = True

# Whether rpkg log should display all branches
# type: bool
log_all = True

# Key to sign commits and tags with. Specifying
# it enables signing.
# type: bool
gpg_keyid =

# In which Copr project to build a package by using
# rpkg build command, in form: user/project or @group/project
# type: string
copr_project =

[lookaside]
# Download URL for DistGit lookaside cache, used by rpkg sources.
# There are some dynamic variables that you can use:
# %(repo_path)s is a fully-namespaced repository name (e.g. rpms/rpkg-util)
# %(ns<n>)s, ..., %(ns2)s, %(ns1)s, %(name)s is %(repo_path)s split into individual components.
# E.g. forks/praiskup/rpms/passwd path will provide variables: %(ns3)s == forks, %(ns2)s == praiskup, %(ns1)s == rpms, %(name)s == passwd
# %(filename)s, %(hashtype)s, %(hash)s fields are read from 'sources' file, if present.
# Further, you can use ${git_props:remote_netloc} interpolation
# variable to base the download URL on git clone URL.
# type: string
download_url =

# Upload URL for DistGit lookaside cache, used by rpkg upload.
# You can use ${git_props:remote_netloc} interpolation
# variable to base the download URL on git clone URL.
# type: string
upload_url =

# For client certificate authentication if employed
# by the server
# type: string
client_cert =

# For client certificate authentication if employed
# by the server
# type: string
client_key =

# For client certificate authentication if employed
# by the server
# type: string
ca_cert =
real talk: gpg_keyid says # type: bool in the comments but it's holding a key id — that's straight from the original, so I'm not touching it. copy the source, not me. 🙈

🌈 DYNAMIC CONFIGURATION SECTIONS 🌈

plot twist #2: there are other config sections that rpkg just kinda spawns during runtime, no config file needed. those are:

  • [DEFAULT] — contains user, path, and pkg_path properties
  • [git_props] — contains a whole lot of git status specific information

you can print the entire final config (yes, including those dynamically added sections) with the rpkg config command. iconic behavior honestly. 🎀

🦋 INTERPOLATION 🦋

when you're setting configuration values, you're allowed to use interpolation to reference another configuration variable — even one from a totally different section. the syntax is:

${<section name>:<param name>}

like for example ${git_props:remote_netloc}. bestie behavior: referencing your friends across the group chat. 💜

there's also a %(<var>)s interpolation for some fields, like lookaside:download_url. and the variables you can interpolate like that are always field-specific — no cross-pollinating, it's a closed circle.

🔥 EXAMPLES 🔥

run the %prep phase of an rpm build

$ rpkg prep
git_dir_pack: packing path /home/clime/rpkg-util
git_dir_pack: Wrote: /tmp/rpkg/rpkg-util-12-ft3gm2mw/rpkg-util-f01b36d7-dirty.tar.gz
Wrote: /tmp/rpkg/rpkg-util-12-ft3gm2mw/rpkg-util.spec
Executing(%prep): /bin/sh -e /var/tmp/rpm-tmp.iqrI6z
+ umask 022
+ cd /tmp/rpkg/rpkg-util-12-ft3gm2mw
+ cd /tmp/rpkg/rpkg-util-12-ft3gm2mw
+ rm -rf rpkg-util
+ /usr/bin/gzip -dc /tmp/rpkg/rpkg-util-12-ft3gm2mw/rpkg-util-f01b36d7-dirty.tar.gz
+ /usr/bin/tar -xof -
+ STATUS=0
+ '[' 0 -ne 0 ']'
+ cd rpkg-util
+ /usr/bin/chmod -Rf a+rX,u+w,g-w,o-w .
+ RPM_EC=0
++ jobs -p
+ exit 0

generate a spec file from a template

$ rpkg spec
Wrote: /tmp/rpkg/rpkg-util-13-53194610/rpkg-util.spec

build an srpm

$ rpkg srpm
git_dir_pack: packing path /home/clime/rpkg-util
git_dir_pack: Wrote: /tmp/rpkg/rpkg-util-14-q3t0g4um/rpkg-util-f01b36d7-dirty.tar.gz
Wrote: /tmp/rpkg/rpkg-util-14-q3t0g4um/rpkg-util.spec
Wrote: /tmp/rpkg/rpkg-util-14-q3t0g4um/rpkg-util-3.prototype.git.229.f01b36d7.dirty.02idw5-1.fc31.src.rpm

🧚 SPEC TEMPLATES 🧚

so spec templates do two things and both are kinda slay. first, they're a way to handle unpacked and packed content. second — and this is the iconic part — they let you auto-generate certain chunks of your spec file straight from the Git repository your spec file lives in. 🌸

⚠️ important: for this to work at all, you need the preprocess_spec configuration option set to True in your rpkg config. no setting, no magic. periodt.

⭐ BASIC EXAMPLE ⭐

Name:       {{{ git_dir_name }}}
Version:    {{{ git_dir_version }}}
Release:    1%{?dist}
Summary:    This is a test package.

License:    GPLv2+
URL:        https://someurl.org
VCS:        {{{ git_dir_vcs }}}

Source:     {{{ git_dir_pack }}}

%description
This is a test package.

%prep
{{{ git_dir_setup_macro }}}

%changelog
{{{ git_dir_changelog }}}

having a spec template like this in your project (instead of just a plain boring spec file) is what lets you build source packages and rpm packages automatically, following the git history of your project. it's giving self-updating. it's giving main character spec file. 👑

💅 MACRO REFERENCE 💅

please, see the dedicated rpkg-macros page. that's where all the macro lore lives.

🌈 USER-DEFINED MACROS 🌈

you can absolutely write your own rpkg macros, bestie. they're basically just standard bash functions, read from the file specified by the user_macros config variable. when one gets used, the standard output of your custom macro is captured, and the {{{ <macro_name> }}} invocation inside your input spec file gets replaced with it. 🪄

here's an example of a custom macro, living in a repo-specific rpkg.macros file:

function my_git_commits_no {
    total_commits=$(git rev-list --all --count)
    echo -n "$total_commits"
}

so if you've got an rpkg.macros file with this content sitting in your project's git top-level directory, then you also need to create an rpkg.conf file in your top-level dir with at least the following content:

[rpkg]
user_macros = ${git_props:root}/rpkg.macros

that's what enables reading of the custom user macros. ✨ and then inside your spec file, you can use a snippet like this:

Release: {{{ my_git_commits_no }}}

which turns your release number into "however many commits exist", generated for you. no manual counting, no suffering. 🫶

⭐ SEE ALSO ⭐

and... that's it. the page just ends here, bestie — nothing else listed, no further reading, no cross-refs. a lil cliffhanger. 💀

aaaand that's the whole manual page, start to finish, every flag, every default, every single {{{ }}}. you ate that. 💖

that little footer down at the bottom is just the boring admin stuff — the source/version stamp and the date it was generated — nothing you need to memorise, just the receipt. go build something iconic with it. 🌸✨🎀🦋👑

📦 where this page comes from