rpkg - Man Page

RPM packaging utility

Synopsis

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

Description

rpkg is a script to manage spec enriched Git repositories - meaning any repositories which contain an rpm spec file. It is designed to work with expanded application sources as well as with standard DistGit tarballs and patches. Note that you should trust the .spec files you work with because many operations (like `rpkg srpm` or `rpkg lint`) involve parsing the spec file, which brings along evaluation of any shell or lua scriplets present in it.

Global Options

 --config CONFIG, -C CONFIG
                       Specify a config file to use.
 --module-name MODULE_NAME
                       Override the module name. Otherwise it is discovered
                       from: Git push URL or Git URL.
 --user USER           Override the discovered user name.
 --path PATH           Define the directory to work in (defaults to cwd).
 --verbose, -v         Run with verbose debug output.
 --debug, -d           Run with debug output.
 -q                    Run quietly only displaying errors.

Command Overview

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

Alias for copr-build

rpkg ci [-h] [-m MESSAGE] [--with-changelog] [-t] [-F FILE] [-p] [-s] [files ...]

Alias for commit

rpkg clean [-h] [--dry-run] [-x]

Remove untracked files

rpkg clog [-h] [--raw] [--outdir OUTDIR] [--spec SPEC]

Make a clog file containing top changelog entry

rpkg clone [-h] [--branches] [--branch BRANCH] [--anonymous] [--depth DEPTH] repo [clone_target] ...

Clone and checkout a repository

rpkg co [-h] [--branches] [--branch BRANCH] [--anonymous] [--depth DEPTH] repo [clone_target] ...

Alias for clone

rpkg commit [-h] [-m MESSAGE] [--with-changelog] [-t] [-F FILE] [-p] [-s] [files ...]

Commit changes

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

Local test rpmbuild compile

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

Build package in Copr Build System

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

Show changes between commits, commit and working tree, etc

rpkg gimmespec [-h]

Print the spec file name

rpkg help [-h]

Show usage

rpkg import [-h] [--skip-diffs] [--offline] srpm

Import srpm content into a module

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

Local test rpmbuild install

rpkg is-packed [-h] [--outdir OUTDIR] [--spec SPEC]

Deprecated. Tell user whether content is packed

rpkg lint [-h] [--info] [--rpmlintconf RPMLINTCONF] [--outdir OUTDIR]

Run rpmlint against local spec and build output if present.

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

Local test rpmbuild binary

rpkg make-source [-h] [--outdir OUTDIR] [--spec SPEC]

Deprecated. Create Source0 from the content of the current working directory after downloading any external sources. The content must be of unpacked type.

rpkg new [-h]

Diff against last tag

rpkg new-sources [-h] files [files ...]

Upload source files

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

Local test rpmbuild prep

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

Pull changes from the remote repository and update the working copy.

rpkg push [-h] [--force]

Push changes and annotated tags to remote repository.

rpkg sources [-h] [--outdir OUTDIR]

Download source files

rpkg spec [-h] [--sources] [--outdir OUTDIR] [--spec SPEC]

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 switch-branch [-h] [-l] [--fetch] [branch]

Work with branches

rpkg tag [-h] [-l] [-d] [-s] [--outdir OUTDIR] [--spec SPEC] [tag]

Management of git tags

rpkg unused-patches [-h] [--outdir OUTDIR] [--spec SPEC]

Print list of patches not referenced by name in the specfile

rpkg upload [-h] files [files ...]

Upload source files

rpkg verify-files [-h] [--outdir OUTDIR]

Locally verify %%files section

rpkg verrel [-h] [--outdir OUTDIR] [--spec SPEC]

Print the name-version-release

Command Reference

rpkg build

 usage: rpkg build [-h] [--config CONFIG] [-w] [--outdir OUTDIR] [--spec SPEC]
                   [project]
 
 Build package in Copr Build System. You need to have copr-cli installed and
 also set up Copr api key. For more information about the api key, see API KEY
 section in copr-cli(1) man page.
 
 positional arguments:
   project          Name of the project in format OWNER/PROJECT. If not
                    specified, project will be set to module name.
 
 optional arguments:
   -h, --help       show this help message and exit
   --config CONFIG  Path to an alternative Copr configuration file
   -w, --wait       Wait for build to finish.
   --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 with ".spec.rpkg" or
                    ".spec" suffix in this order.
 

rpkg ci

 usage: rpkg ci [-h] [-m MESSAGE] [--with-changelog] [-t] [-F FILE] [-p] [-s]
                [files ...]
 
 Alias for commit.
 
 positional arguments:
   files                 Optional list of specific files to commit
 
 optional arguments:
   -h, --help            show this help message and exit
   -m MESSAGE, --message MESSAGE
                         Use the given <msg> as the commit message summary
   --with-changelog      Get the last changelog from SPEC as commit message
                         content. This option must be used with -m together.
   -t, --tag             Create a tag for this commit
   -F FILE, --file FILE  Take the commit message from the given file
   -p, --push            Commit and push as one action
   -s, --signoff         Include a signed-off-by
 

rpkg clean

 usage: rpkg clean [-h] [--dry-run] [-x]
 
 This command can be used to clean up your working directory. By default it
 will follow .gitignore rules.
 
 optional arguments:
   -h, --help     show this help message and exit
   --dry-run, -n  Perform a dry-run
   -x             Do not follow .gitignore rules
 

rpkg clog

 usage: rpkg clog [-h] [--raw] [--outdir OUTDIR] [--spec SPEC]
 
 This will create a file named "clog" that contains the latest rpm changelog
 entry. The leading "- " text will be stripped.
 
 optional arguments:
   -h, --help       show this help message and exit
   --raw            Generate a more "raw" clog without twiddling the contents
   --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 with ".spec.rpkg" or
                    ".spec" suffix in this order.
 

rpkg clone

 usage: rpkg clone [-h] [--branches] [--branch BRANCH] [--anonymous]
                   [--depth DEPTH]
                   repo [clone_target] ...
 
 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                  Name of the repository to clone
   clone_target          Directory in which to clone the repository
   extra_args            Custom arguments that are passed to the 'git clone'.
                         Use '--' to separate them from other arguments.
 
 optional arguments:
   -h, --help            show this help message and exit
   --branches, -B        Do an old style checkout with subdirs for branches
   --branch BRANCH, -b BRANCH
                         Check out a specific branch
   --anonymous, -a       Check out a module anonymously
   --depth DEPTH         Create a shallow clone with a history truncated to the
                         specified number of commits
 

rpkg co

 usage: rpkg co [-h] [--branches] [--branch BRANCH] [--anonymous]
                [--depth DEPTH]
                repo [clone_target] ...
 
 Alias for clone.
 
 positional arguments:
   repo                  Name of the repository to clone
   clone_target          Directory in which to clone the repository
   extra_args            Custom arguments that are passed to the 'git clone'.
                         Use '--' to separate them from other arguments.
 
 optional arguments:
   -h, --help            show this help message and exit
   --branches, -B        Do an old style checkout with subdirs for branches
   --branch BRANCH, -b BRANCH
                         Check out a specific branch
   --anonymous, -a       Check out a module anonymously
   --depth DEPTH         Create a shallow clone with a history truncated to the
                         specified number of commits
 

rpkg commit

 usage: rpkg commit [-h] [-m MESSAGE] [--with-changelog] [-t] [-F FILE] [-p]
                    [-s]
                    [files ...]
 
 This invokes a git commit. All tracked files with changes will be committed
 unless a specific file list is provided. $EDITOR will be used to generate a
 changelog message unless one is given to the command. A tag or push can be
 done at the same time.
 
 positional arguments:
   files                 Optional list of specific files to commit
 
 optional arguments:
   -h, --help            show this help message and exit
   -m MESSAGE, --message MESSAGE
                         Use the given <msg> as the commit message summary
   --with-changelog      Get the last changelog from SPEC as commit message
                         content. This option must be used with -m together.
   -t, --tag             Create a tag for this commit
   -F FILE, --file FILE  Take the commit message from the given file
   -p, --push            Commit and push as one action
   -s, --signoff         Include a signed-off-by
 

rpkg compile

 usage: rpkg compile [-h] [--target TARGET] [--with OPTION] [--without OPTION]
                     [--short-circuit] [--nocheck] [--outdir OUTDIR]
                     [--spec SPEC]
 
 This command calls rpmbuild to compile the source. By default the prep and
 configure stages will be done as well, unless the short-circuit option is
 used.
 
 optional arguments:
   -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.
   --short-circuit   short-circuit compile
   --nocheck         nocheck compile
   --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 with ".spec.rpkg" or
                     ".spec" suffix in this order.
 

rpkg copr-build

 usage: rpkg copr-build [-h] [--config CONFIG] [-w] [--outdir OUTDIR]
                        [--spec SPEC]
                        [project]
 
 Build package in Copr Build System. You need to have copr-cli installed and
 also set up Copr api key. For more information about the api key, see API KEY
 section in copr-cli(1) man page.
 
 positional arguments:
   project          Name of the project in format OWNER/PROJECT. If not
                    specified, project will be set to module name.
 
 optional arguments:
   -h, --help       show this help message and exit
   --config CONFIG  Path to an alternative Copr configuration file
   -w, --wait       Wait for build to finish.
   --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 with ".spec.rpkg" or
                    ".spec" suffix in this order.
 

rpkg diff

 usage: rpkg diff [-h] [--cached] [files ...]
 
 Use git diff to show changes that have been made to tracked files. By default
 cached changes (changes that have been git added) will not be shown.
 
 positional arguments:
   files       Optionally diff specific files
 
 optional arguments:
   -h, --help  show this help message and exit
   --cached    View staged changes
 

rpkg gimmespec

 usage: rpkg gimmespec [-h]
 
 Print the spec file name.
 
 optional arguments:
   -h, --help  show this help message and exit
 

rpkg help

 usage: rpkg help [-h]
 
 Show usage.
 
 optional arguments:
   -h, --help  show this help message and exit
 

rpkg import

 usage: rpkg import [-h] [--skip-diffs] [--offline] srpm
 
 This will extract sources, patches, and the spec file from an srpm and update
 the current module accordingly. It will import to the current branch by
 default.
 
 positional arguments:
   srpm          Source rpm to import
 
 optional arguments:
   -h, --help    show this help message and exit
   --skip-diffs  Don't show diffs when import srpms
   --offline     Do not upload files into lookaside cache
 

rpkg install

 usage: rpkg install [-h] [--target TARGET] [--with OPTION] [--without OPTION]
                     [--short-circuit] [--nocheck] [--outdir OUTDIR]
                     [--spec SPEC]
 
 This will call rpmbuild to run the install section. All leading sections will
 be processed as well, unless the short-circuit option is used.
 
 optional arguments:
   -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.
   --short-circuit   short-circuit install
   --nocheck         nocheck install
   --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 with ".spec.rpkg" or
                     ".spec" suffix in this order.
 

rpkg is-packed

 usage: rpkg is-packed [-h] [--outdir OUTDIR] [--spec SPEC]
 
 Deprecated. Determine whether the package content in the working directory is
 packed or unpacked and print that information to the screen.
 
 optional arguments:
   -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 with ".spec.rpkg" or
                    ".spec" suffix in this order.
 

rpkg lint

 usage: rpkg lint [-h] [--info] [--rpmlintconf RPMLINTCONF] [--outdir OUTDIR]
 
 Rpmlint can be configured using the --rpmlintconf/-r option or by setting a
 .rpmlint file in the working directory.
 
 optional arguments:
   -h, --help            show this help message and exit
   --info, -i            Display explanations for reported messages
   --rpmlintconf RPMLINTCONF, -r RPMLINTCONF
                         Use a specific configuration file for rpmlint
   --outdir OUTDIR       Directory with rpm items to be linted or just a single
                         rpm item like a .spec file. If not specified, a
                         directory from base output path will be selected.
 

rpkg local

 usage: rpkg local [-h] [--target TARGET] [--with OPTION] [--without OPTION]
                   [--outdir OUTDIR] [--spec SPEC]
 
 Locally test run of rpmbuild producing binary RPMs. The rpmbuild output will
 be logged into a file named .build-%{version}-%{release}.log
 
 optional arguments:
   -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 with ".spec.rpkg" or
                     ".spec" suffix in this order.
 

rpkg make-source

 usage: rpkg make-source [-h] [--outdir OUTDIR] [--spec SPEC]
 
 Deprecated. Puts content of the current working directory into a gzip-
 compressed archive named according to Source0 filename as specified in the
 .spec file. The content must be of unpacked type, otherwise no action is
 taken. Unpacked content is such that it contains a .spec file that references
 no present source or patch (typically it contains only Source0 being generated
 automatically) and there is at least one file not in the list of ignored
 content (README, README.md, sources, LICENSE, tito.props, hidden files, .spec
 file). Note that by invoking this command with --outdir ./, the directory
 content becomes "packed".
 
 optional arguments:
   -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 with ".spec.rpkg" or
                    ".spec" suffix in this order.
 

rpkg new

 usage: rpkg new [-h]
 
 This will use git to show a diff of all the changes (even uncommitted changes)
 since the last git tag was applied.
 
 optional arguments:
   -h, --help  show this help message and exit
 

rpkg new-sources

 usage: rpkg new-sources [-h] files [files ...]
 
 This will upload new source file(s) to lookaside cache, and all file names
 listed in sources file will be replaced. .gitignore will be also updated with
 new uploaded file(s). Please remember to commit them.
 
 positional arguments:
   files
 
 optional arguments:
   -h, --help  show this help message and exit
 

rpkg prep

 usage: rpkg prep [-h] [--target TARGET] [--with OPTION] [--without OPTION]
                  [--outdir OUTDIR] [--spec SPEC]
 
 Use rpmbuild to "prep" the sources (unpack the source archive(s) and apply any
 patches.)
 
 optional arguments:
   -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 with ".spec.rpkg" or
                     ".spec" suffix in this order.
 

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.
 
 optional arguments:
   -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
 
 See git pull --help for more details
 

rpkg push

 usage: rpkg push [-h] [--force]
 
 Push changes and annotated tags to remote repository.
 
 optional arguments:
   -h, --help   show this help message and exit
   --force, -f  Force push
 

rpkg sources

 usage: rpkg sources [-h] [--outdir OUTDIR]
 
 Download source files
 
 optional arguments:
   -h, --help       show this help message and exit
   --outdir OUTDIR  Directory to download files into (defaults to pwd)
 

rpkg spec

 usage: rpkg spec [-h] [--sources] [--outdir OUTDIR] [--spec SPEC]
 
 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.
 
 optional arguments:
   -h, --help       show this help message and exit
   --sources        Enable source generation by the input spec template. By
                    default disabled.
   --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 with ".spec.rpkg" or
                    ".spec" suffix in this order.
 

rpkg srpm

 usage: rpkg srpm [-h] [--target TARGET] [--with OPTION] [--without OPTION]
                  [--outdir OUTDIR] [--spec SPEC]
 
 Create a source rpm
 
 optional arguments:
   -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 with ".spec.rpkg" or
                     ".spec" suffix in this order.
 

rpkg switch-branch

 usage: rpkg switch-branch [-h] [-l] [--fetch] [branch]
 
 This command can switch to a local git branch. If provided with a remote
 branch name that does not have a local match it will create one. It can also
 be used to list the existing local and remote branches.
 
 positional arguments:
   branch      Branch name to switch to
 
 optional arguments:
   -h, --help  show this help message and exit
   -l, --list  List both remote-tracking branches and local branches
   --fetch     Fetch new data from remote before switch
 

rpkg tag

 usage: rpkg tag [-h] [-l] [-d] [-s] [--outdir OUTDIR] [--spec SPEC] [tag]
 
 This command uses git to create, list, or delete tags.
 
 positional arguments:
   tag              Name of the tag
 
 optional arguments:
   -h, --help       show this help message and exit
   -l, --list       List all tags with a given pattern, or all if not pattern
                    is given
   -d, --delete     Delete a tag
   -s, --skip-edit  Skips changelog editing when creating a tag.
   --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 with ".spec.rpkg" or
                    ".spec" suffix in this order.
 

rpkg unused-patches

 usage: rpkg unused-patches [-h] [--outdir OUTDIR] [--spec SPEC]
 
 Print list of patches not referenced by name in the specfile.
 
 optional arguments:
   -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 with ".spec.rpkg" or
                    ".spec" suffix in this order.
 

rpkg upload

 usage: rpkg upload [-h] files [files ...]
 
 This command will upload new source file(s) to lookaside cache. Source file
 names are appended to sources file, and .gitignore will be also updated with
 new uploaded file(s). Please remember to commit them.
 
 positional arguments:
   files
 
 optional arguments:
   -h, --help  show this help message and exit
 

rpkg verify-files

 usage: rpkg verify-files [-h] [--outdir OUTDIR]
 
 Locally run 'rpmbuild -bl' to verify the spec file's %files sections. This
 requires a successful run of 'rpkg install' in advance.
 
 optional arguments:
   -h, --help       show this help message and exit
   --outdir OUTDIR  Output directory with build results.
 

rpkg verrel

 usage: rpkg verrel [-h] [--outdir OUTDIR] [--spec SPEC]
 
 Print the name-version-release.
 
 optional arguments:
   -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 with ".spec.rpkg" or
                    ".spec" suffix in this order.
 

Configuration

rpkg reads configuration options from the following files in this order:

   /etc/rpkg.conf, ~/.config/rpkg.conf, <gitroot>/rpkg.conf, ./rpkg.conf

Configuration found in ./rpkg.conf has the highest priority. Configuration in /etc/rpkg.conf has the lowest priority. <gitroot> placeholder above means the top level of the Git repository we are working in. If we are in a plain directory and all our parent directories are also plain, reading of <gitroot>/rpkg.conf is simply skipped.

Default Commented Configuration

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

   # generate tarball from sources named
   # according to Source0 definition in
   # a spec file. Used by `rpkg srpm`.
   # Deprecated by spec templates.
   auto_pack = False

   # base directory where results should be stored
   base_output_path = /tmp/rpkg

   # sets permanent value for --module-name option
   # for each executed rpkg command
   # module_name = @group/project

   [git]
   # download URL for DistGit lookaside cache, used by `rpkg sources` command
   # %(ns1)s, %(pkg)s are parts of a module name (e.g. rpms/rpkg-util)
   # %(filename)s, %(hashtype)s, %(hash)s, %(filename)s fields are read from 'sources' file if present
   lookaside = https://src.fedoraproject.org/repo/pkgs/%(ns1)s/%(pkg)s/%(filename)s/%(hashtype)s/%(hash)s/%(filename)s

   # upload URL for DistGit lookaside cache, used by `rpkg upload`
   lookaside_cgi = https://src.fedoraproject.org/repo/pkgs/upload.cgi

   # default Git repository URL, used by `rpkg clone <module>`
   gitbaseurl = ssh://%(user)s@pkgs.fedoraproject.org/%(module)s

   # default anonymous Git repository URL, used by `rpkg clone -a <module>`
   anongiturl = https://src.fedoraproject.org/%(module)s

Examples

Run %prep phase of an rpm build:

   $ rpkg prep
   git_pack: packing directory /home/clime/rpkg-util
   git_pack: Wrote: /tmp/rpkg/rpkg-util-1-j8x35rb3/rpkg-util-2.2.git.18.5b6a884.tar.gz
   Wrote: /tmp/rpkg/rpkg-util-1-j8x35rb3/rpkg-util.spec
   Executing(%prep): /bin/sh -e /var/tmp/rpm-tmp.vE42SH
   + umask 022
   + cd /tmp/rpkg/rpkg-util-1-j8x35rb3
   + cd /tmp/rpkg/rpkg-util-1-j8x35rb3
   + rm -rf rpkg-util-2.2.git.18.5b6a884
   + /usr/bin/gzip -dc /tmp/rpkg/rpkg-util-1-j8x35rb3/rpkg-util-2.2.git.18.5b6a884.tar.gz
   + /usr/bin/tar -xof -
   + STATUS=0
   + '[' 0 -ne 0 ']'
   + cd rpkg-util-2.2.git.18.5b6a884
   + /usr/bin/chmod -Rf a+rX,u+w,g-w,o-w .
   + exit 0

For the following command, you need to have a project in COPR created. See quick tutorial at

https://docs.pagure.org/copr.copr/user_documentation.html#quick-start

on how to do it.

   $ rpkg build
   git_pack: packing directory /home/clime/rpkg-util
   git_pack: Wrote: /tmp/rpkg/rpkg-util-2-ab6awb8y/rpkg-util-2.2.git.18.0cb6974.tar.gz
   Wrote: /tmp/rpkg/rpkg-util-2-ab6awb8y/rpkg-util.spec
   Wrote: /tmp/rpkg/rpkg-util-2-ab6awb8y/rpkg-util-2.2.git.18.0cb6974-1.fc28.src.rpm
   Uploading package /tmp/rpkg/rpkg-util-2-ab6awb8y/rpkg-util-2.2.git.18.0cb6974-1.fc28.src.rpm
   100% |################################| 122kB 359kB/s eta 0:00:00
   Build was added to rpkg-util:
     https://copr.fedorainfracloud.org/coprs/build/782327/
   Created builds: 782327

Here you can see a simple operation of generation spec file from a template:

   $ rpkg spec
   Wrote: /tmp/rpkg/rpkg-util-3-1u34plfx/rpkg-util.spec

Spec Templates

Apart from being useful as a means to handle unpacked as well as packed content, they also make it possible to generate certain parts of your spec file automatically from a Git repository where your spec file is located. You need to have "spec_preprocess" configuration option set to True in rpkg config to use this functionality.

Basic Example

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

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

   Source:     {{{ git_pack }}}

   %description
   This is a test package.

   %prep
   {{{ git_setup_macro }}}

   %changelog
   {{{ git_changelog }}}

Having a spec template like this in your project (instead of just a plain spec file) allows you to build source and rpm packages automatically following git history of your project.

Macro Reference

BASE GIT MACROS

Without any parameters, these macros work on repository level and use globally available repository information.

NOTE: If your local repository is not properly initialized or if, for example, the .git metadata directory in your local tree has been renamed or removed, operation of the base macros can get out of the intended scope. It is therefore recommended to use more specific git_dir_* macros where possible, which are always bound to the directory where the input spec file is located. This is mainly relevant for git_pack and git_archive macros (see below).

Output of every git macro call is cached and other macros are made to take those cached values into account by default. You can see that a macro uses a cached value as a default input parameter value by looking at its function header definition and searching for the `cached` keyword.

E.g.

   git_version [name="$(cached git_name)"] [lead=0] [follow=]

Default value for name in this definition is derived from the cached output of the previously invoked `git_name` macro. If `git_name` macro has not been invoked or if its output was an empty string, the default value for the `name=` parameter above will be also an empty string.

Note that $(cached_git_name_version) in the function header definitions below is an alias for "$(cached git_name)-$(cached git_version)".

git_name [name=] [prepend=] [append=]

Without any parameters, lookup remote URL for the currently active branch and output its basename with .git suffix stripped. If the remote URL could not be determined, use "origin" remote URL instead.

   Optional arguments:
       name     the base name to be output
       prepend  string to be prepended to the base name
       append   string to be appended to the base name

git_version [name="$(cached git_name)"] [lead=0] [follow=]

Output version of a subpackage given by ${name}. The version is a string constructed of the following parts:

   "${lead}.${follow}${commit_count_appendix}${wtree_appendix}"

${lead} is a mandatory argument of the macro. By default it is set to zero.

${follow} (if not specified) is obtained from the follow part of the latest tag made for the subpackage given by ${name}.

${commit_count_appendix} is generated only if the current commit is not tagged for the given subpackage and it is composed of the following parts

   .git.<commit_count>.<latest_commit_short_hash>

Commit count is a number of commits from the latest tag on the given subpackage.

${wtree_appendix} is generated only if the currently checked out working tree is dirty. It is composed of the following parts:

   .wtree.<encoded_latest_file_status_change>

   Optional arguments:
       name     name of a subpackage
       lead     major version substring
       follow   minor version substring, dynamically generated if not specified

   Environment variables:
       VERSION_BUMP: if set to a non-empty value, the following procedure is applied
       to get the version string:

       If $follow is specified by user explicitly, return $lead.$follow.

       Otherwise, extract $follow from the latest tag as the last version component (after the last dot)
       and return $lead.$follow+1. If $follow is not a number, throw an error (manual setting of follow
       is needed).

       rpkg sets the VERSION_BUMP variable into the preprocessing environment during
       execution of `rpkg tag` subcommand. Otherwise, it is unset.

git_vcs [subtree=]

Output pseudo repository URL pointing the currently checked out tree.

Example output: git+ssh://git@pagure.io/test-project.git#dadef2a8b9554e94797a7336261192e02d5d9351:

   Optional arguments:
       subtree     path to a subtree to generate the URL for

git_pack [path="$(git rev-parse --show-toplevel)"] [dir_name="$(cached_git_name_version)"] [source_name="$(cached_git_name_version).tar.gz"]

Pack the whole working tree content (including untracked content) into a gzipped source tarball and output $source_name, which is a filename of the created tarball. Uses GNU tar to do the job. Files ignored by git as well as .git metadata directory will be excluded from the resulting tarball.

   Optional arguments:
       path         path to a specific subdirectory to be packed
       dir_name     top-level directory name in the created tarball
       source_name  filename of the created source tarball

   Enviroment variables:
       OUTDIR: if empty, git_pack will not generate any sources, only the source filename will be output

       rpkg sets OUTDIR, only if the tarball is actually needed to be generated. It does not set it
       when `rpkg spec` is called (without any additional arguments).

git_archive [path="$(git rev-parse --show-toplevel)"] [dir_name="$(cached_git_name_version)"] [source_name="$(cached_git_name_version).tar.gz"]

Pack the latest commit tree content into a gzipped source tarball and output $source_name, which is a filename of the created tarball. Uses `git archive` to do the job. Note that this macro will refuse to generate a tarball if your working tree is dirty.

   Optional arguments:
       path         path to a specific subdirectory to be packed
       dir_name     top-level directory name in the created tarball
       source_name  filename of the created source tarball

   Enviroment variables:
       OUTDIR: if empty, git_archive will not generate any sources, only the source filename will be output

       rpkg sets OUTDIR, only if the tarball is actually needed to be generated. It does not set it
       when `rpkg spec` is called (without any additional arguments).

git_setup_macro [dir_name="$(cached_git_name_version)"]

Output %setup rpm macro for the given top-level source-tarball directory.

   Optional arguments:
       dir_name     name of the top-level directory in the source-tarball

git_changelog [name="$(cached git_name)"] [since_tag=] [until_tag=] [header_locale=POSIX] [header_date_format="%a %b %d %Y"] [body_wrap=80]

Output rpm spec changelog as generated from tag messages for the subpackage given by ${name}.

   Optional arguments:
       name                name of the subpackage to generate the changelog for
       since_tag           start the changelog records with this tag
       until_tag           end the changelog records with this tag
       header_locale       locale to be used when changelog record date is being generated
       header_date_format  date format to be used in the changelog record headers
       body_wrap           maximum allowed line length for changelog body

When `rpkg tag` is called, it allows you to specify a tag message. This is the message that will be used as a changelog record body.

GIT_DIR MACROS

These macros operate on a directory level. In particular, on a directory where the input spec file template is located. They are basically aliases to the GIT BASE MACROS with some input values set specifically for the directory-level operation. The input spec template location is given by INPUT_PATH environment variable set by rpkg. You can influence it from the command line by explicitly specifying --spec <template_path> argument for rpkg subcommands that support it.

Below you can see to what the GIT DIR macros expand. In some cases, the macro is a direct alias to the underlying git base macro.

git_dir_name

   git_name append="-$(git -C "$(dirname "$INPUT_PATH")" rev-parse --show-prefix | path_to_name_suffix)"

   Outputs repository origin URL basename appended with the path (after slash to dash substitution) from the repository
   root to the spec file's directory.

git_dir_version

   git_version

git_dir_vcs

   git_vcs subtree="$(git -C "$(dirname "$INPUT_PATH")" rev-parse --show-prefix)"

   Outputs VCS pseudo URL pointing to the spec file's subdirectory.

git_dir_pack

   git_pack path="$(dirname "$INPUT_PATH")"

   Packs spec file's subdirectory by using GNU tar.

git_dir_archive

   git_archive path="$(dirname "$INPUT_PATH")"

   Packs spec file's subdirectory by using `git archive`.

git_dir_setup_macro

   git_setup_macro

git_dir_changelog

   git_changelog

GIT_CWD MACROS

These macros operate on a directory level. In particular, on a rpkg's working directory. Again, they are aliases to the GIT BASE MACROS with some input values set specifically for the directory-level operation.

You can influence the rpkg's working dir from the command line by explicitly specifying its --path argument.

Below you can see to what the GIT_CWD macros expand. In some cases, the macro is a direct alias for the underlying git base macro.

git_cwd_name

   git_name append="-$(git -C "$(pwd)" rev-parse --show-prefix | path_to_name_suffix)"

   Outputs repository origin URL basename appended with the rpkg's working directory path (after slash to dash substitution).

git_cwd_version

   git_version

git_cwd_vcs

   git_vcs subtree="$(git -C "$(pwd)" rev-parse --show-prefix)"

   Outputs VCS pseudo URL pointing to the rpkg's working directory.

git_cwd_pack

   git_pack path="$(pwd)"

   Packs rpkg's working directory by using GNU tar.

git_cwd_archive

   git_archive path="$(pwd)"

   Packs rpkg's working directory by using `git archive`.

git_cwd_setup_macro

   git_setup_macro

git_cwd_changelog

   git_changelog

User-Defined Macros

You can define your own rpkg macros that are basically just standard bash functions read from rpkg.macros file placed in an rpkg's working directory. Standard output of your custom macro will be captured and the {{{ <macro_name> }}} invocation in an input spec file will be replaced with it.

Example of a custom macro placed in rpkg.macros file:

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

Auto-Packing (Deprecated)

Auto-packing works only if auto_pack configuration option is set to True and only if the content you are working with is not packed (see `rpkg is-packed`).

When invoking `rpkg srpm` on an unpacked content, rpkg will download external sources (if any) and then it will generate a tarball from the whole content of the working directory named according to Source0 definition present in the associated .spec file. This tarball and the .spec file are then passed to rpmbuild to generate the resulting srpm.

Packed VS Unpacked

NOTE: This article relates to deprecated auto_pack feature.

While it is quite intuitive what is packed content (.spec + tarballs + patches) and what is unpacked content (.spec + original application source files), it might be useful to know how exactly rpkg differentiates between these two. You can go through the following examples to get overview how this tool exactly works.

Packed Content

   $ cd source0-present-example
   $ grep -E '(Source|Patch)' testpkg.spec
   Source0: foo.tar.gz
   $ ls .
   foo.tar.gz testpkg.spec
   $ rpkg make-source
   Could not execute make_source: Not an unpacked content.
   $ rpkg srpm
   Failed to get module name from Git url or pushurl.
   Wrote: source0-present-example/testpkg-1-1.fc25.src.rpm

   The error about module name is caused by running `rpkg`
   on a plain directory content and not a Git repo. In this
   case, module name is read out from the spec file. The
   error about not being able to make source is expected for
   packed content (tarballs to be put into srpm are expected
   to be present already).

   $ cd only-ignored-files-example
   $ grep -E '(Source|Patch)' testpkg.spec
   Source0: https://example.org/foo.tar.gz
   $ ls .
   README.md testpkg.spec
   $ rpkg make-source
   Could not execute make_source: Not an unpacked content.
   $ echo '%_disable_source_fetch 0' >> ~/.rpmmacros
   $ rpkg srpm
   Failed to get module name from Git url or pushurl
   warning: Downloading https://example.org/foo.tar.gz to only-ignored-files-example/foo.tar.gz
   Wrote: only-ignored-files-example/testpkg-1-1.fc25.src.rpm

   In this example, sources are downloaded from network when
   srpm is being built. The %_disable_source_fetch rpm macro
   must be set to 0 and the tarball url must be valid for this
   to work. The content is recognized as packed because there
   are only ignored files in the directory (.spec and readmes).

Unpacked Content

   $ cd cpp-source-file-present-example
   $ git init .
   $ git remote add origin https://github.com/testpkg.git
   $ grep -E '(Source|Patch)' testpkg.spec
   Source0: foo.tar.gz
   $ ls .
   main.cpp testpkg.spec
   $ rpkg make-source
   Wrote: cpp-source-file-present-example/foo.tar.gz
   $ rpkg srpm
   Wrote: cpp-source-file-present-example/testpkg-1-1.fc25.src.rpm

   foo.tar.gz (the only Source referenced from the .spec file) is
   not present and there is unignored main.cpp file that makes the
   content recognized as unpacked. When `rpkg make-source` is invoked,
   foo.tar.gz is created and will contain the main.cpp file (as
   well as the .spec metadata file but that is just because the
   whole content directory is packed). Note that the error about
   failing to get module name from Git url disappeared because
   we have run `git init .` and `git remote add ...`.

See Also

https://pagure.io/rpkg-util/

Info

2021-02-20 rpm-packager