fbrnch: Build and create Fedora package repos and branches

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

fbrnch (fedora branch) is a convenient packaging tool for Fedora Packagers, with integration for Bugzilla, Koji, and Bodhi.

Features include:

and many more commands.

[Skip to Readme]


Versions 0.7.1, 0.7.2, 0.7.3, 0.8.0, 0.9, 0.9.1,,, 1.0.0, 1.1, 1.1.1, 1.1.2, 1.2, 1.2.1, 1.3, 1.3.1, 1.3.2, 1.3.3, 1.4
Change log CHANGELOG.md
Dependencies aeson, async, base (>=4.9 && <5), bugzilla-redhat (>=0.3), bytestring, config-ini, directory (>=1.2.3), email-validate, extra, filepath, http-conduit, http-directory (>=0.1.5), http-query, koji, lens, lens-aeson, network-uri, optparse-applicative, pretty-terminal, process, rpm-nvr, rpmbuild-order (>=0.4.5), semigroups, simple-cmd (>=0.2.0), simple-cmd-args (>=0.1.6), text, time, typed-process (>=, unordered-containers, utf8-string, xdg-basedir [details]
License GPL-2.0-only
Copyright 2019-2021 Jens Petersen
Author Jens Petersen <petersen@redhat.com>
Maintainer Jens Petersen <petersen@fedoraproject.org>
Category Distribution
Home page https://github.com/juhp/fbrnch
Bug tracker https://github.com/juhp/fbrnch/issues
Source repo head: git clone https://github.com/juhp/fbrnch.git
Uploaded by JensPetersen at 2021-08-01T13:52:27Z


Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Readme for fbrnch-

[back to package description]

fbrnch (fedora branch) packager tool

GPL-2+ license GitHub CI Hackage

A tool to help Fedora Packagers build package branches and add new packages.

Fedora developers use a lot of time building packages across releases and workflow for adding new packages, etc. fbrnch was made to help (semi-)automate common workflows to save time and effort.

fbrnch is distributed under the GPL license version 2 or later.


fbrnch is a Fedora Packager client which tries to automate some common tasks like:

and more.


Creating new packages/branches

Creating a new package

$ fbrnch create-review [my-new-package]

This will create (or update) an srpm, run rpmlint, then upload it to fedorapeople, perform a scratch build, and open a Review Request in Bugzilla (similar to fedora-create-review).

Update a package review

$ fbrnch update-review [my-new-package]

Similar to create-review: it uploads the updated files to fedorapeople and posts the updated package urls to the open package review.

List open package reviews

To list one's open package reviews:

$ fbrnch reviews

They can be filtered by status with various options like --approved or --created.

One can also search for the review(s) of a specific package with:

$ fbrnch find-review package-name

Request repos

Once a review has been approved

$ fbrnch request-repos

will request repos for approved package(s) and offer to request branches.

Import a new package

After the repo has been created

$ fbrnch import

will clone the repo and offer to import the srpm directly from the latest url in the approved package review, which can then be built directly into Koji Rawhide and the package review is updated.

Request branches

If you prefer you can request branches after the repo is created or package imported with

$ fbrnch request-branches

which will be prompt for which branches you want, unless already given.

Optionally a mock build per branch can be done first.

Cloning and switching branch

Clone one or more packages:

$ fbrnch clone package ...

There are also options to clone all one's packages or another user's packages.

One can change the branch of one or more packages:

$ fbrnch switch f34 [package] ...

You can also git pull over packages:

$ fbrnch pull [package] ...

List packages and branches

You can list packages in dist-git pagure with

$ fbrnch list PATTERN

with globbing.

Branches of a package can be listed:

$ fbrnch branches -B [package] ...

You can use the --remote option if you don't have the package checked out.

Package status

$ fbrnch status -B [package]

outputs information about the status of each branch. The status command can also be used with --reviews to check the build status of new packages.

You can output package's nvr's from local git:

$ fbrnch nvr -B [package]

and list package bugs:

$ fbrnch bugs [package]

Commit, Merging and Building in Koji

You can commit to the current branch:

$ fbrnch commit

It uses any rpm changelog, or you can pass -m "..." or amend with -a.

You can merge branches with:

$ fbrnch merge f33 package

which will offer to merge f34 (or some of it) into f33.

Merging can also be done together with building:

$ fbrnch build f34 package

will ask if you want to merge newer commits from a newer branch, then push and build it.

If the branch is also already pushed and NVR built it will be skipped. Branch builds are pushed to Bodhi.

You can also build all branches:

$ fbrnch build -B package

or all fedora branches:

$ fbrnch build -F package

or all epel branches:

$ fbrnch build -E package

Scratch builds can also be done:

$ fbrnch scratch rawhide

optionally a different koji --target can be given.

You can sort packages by build dependency order:

$ fbrnch sort rawhide package1 package2 package3 package4 ...

Local commands

$ fbrnch prep rawhide package

Build locally:

$ fbrnch local

this works in the current package dir like other commands, installing any missing dependencies with sudo dnf builddep.

Or one can specify the path to the package.

Locally build and install:

$ fbrnch install package1 package2 package3 ...

You can use:

$ fbrnch install-deps [package]

to only install the dependencies of a package.


$ fbrnch rename-master [package]

to rename an old master branch locally to rawhide.

Parallel building

fbrnch can sort packages automatically and build them in parallel in Koji in dependency layers (using low-priority background builds to avoid grabbing too many Koji resources).

$ fbrnch parallel --sidetag rawhide pkg-x pkg-y pkg-z pkg-xy pkg-xy-z

generates a sidetag and builds a list of packages there in parallel ordered by build dependencies.

Except for rawhide using a sidetag is required, so you need to manage and select them if using more than one per branch with --target.

Other commands

There are more commands like copr and graph.

$ fbrnch --version
$ fbrnch --help
Fedora package branch building tool

Usage: fbrnch [--version] COMMAND
  This tool helps with updating and building package branches

Available options:
  -h,--help                Show this help text
  --version                Show version

Available commands:
  clone                    clone packages
  switch                   Switch branch
  nvr                      Print name-version-release
  status                   Status package/branch status
  merge                    Merge from newer branch
  build                    Build package(s) in Koji
  list                     List packages in pagure
  branches                 List package branches
  parallel                 Parallel build packages in Koji
  sidetags                 List user's side-tags
  override                 Tag builds into buildroot override in Koji
  waitrepo                 Wait for build to appear in Koji buildroot
  scratch                  Scratch build package in Koji
  update                   Update package in dist-git to newer version
  sort                     Sort packages in build dependency order
  prep                     Prep sources
  local                    Build locally
  srpm                     Build srpm
  diff                     Diff local changes
  log                      Show commits between branches
  mock                     Local mock build
  install-deps             Install package build dependencies
  install                  Build locally and install package(s)
  not-installed            Packages not installed locally
  bugs                     List package bugs
  bump                     Bump release for package
  commit                   Git commit packages
  pull                     Git pull packages
  create-review            Create a Package Review request
  update-review            Update a Package Review
  review-package           Run fedora-review on a package Review Request bug
  reviews                  List package reviews
  request-repos            Request dist git repo for new approved packages
  import                   Import new approved created packages from bugzilla
  request-branches         Request branches for approved created packages
  find-review              Find package review bug
  command                  Run shell command in package dirs ($p)
  copr                     Build package(s) in Fedora Copr
  rename-master            Rename local master branch to rawhide
  graph                    Output dependency graph

Known issues

Motivation, history, talks

This project started off (as "fedbrnch") basically as a simple tool to build a package across branches (ie for current releases). Then bugzilla and Bodhi integration was added, and gradually more features, including some generic commands across packages which had already been done before in fedora-haskell-tools.

I have given a couple of short talks about fbranch:


fbrnch is packaged in Fedora: sudo dnf install fbrnch.

Build from source

  1. Install openssl-devel

  2. Clone the git repo and in the source dir, setup the git submodules:

git submodule update --init

  1. Then either:

a) using stack >= 2.1: stack install


b) with cabal-install (probably 2.4 or later) and cabal-rpm:

$ cabal-rpm builddep
$ cabal new-install --installdir=~/bin

Required runtime tools

fbrnch currently uses these fedora cli tools:

It also makes use of:


Bug reports, feedback, and pull requests welcome.

Please report any unsupported or unintuitive workflow steps.

See the TODO list and also the FIXME comments scattered across the source. Do open an issue before embarking on large changes.

People who have committed: