Polybar Documentation¶
Note
This is still very much a work-in-progress. Most information is still to be found on our GitHub Wiki. We will migrate the wiki content step-by-step.
Welcome to the official polybar documentation.
polybar(1)¶
SYNOPSIS¶
polybar [OPTIONS]… BAR
DESCRIPTION¶
Polybar aims to help users build beautiful and highly customizable status bars for their desktop environment, without the need of having a black belt in shell scripting.
OPTIONS¶
-
-h
,
--help
¶
Display help text and exit
-
-v
,
--version
¶
Display build details and exit
-
-l
,
--log
=LEVEL
¶ - Set the logging verbosity (default: notice)LEVEL is one of: error, warning, notice, info, trace
-
-q
,
--quiet
¶
Be quiet (will override -l)
-
-c
,
--config
=FILE
¶ Specify the path to the configuration file. By default, the configuration file is loaded from:
$XDG_CONFIG_HOME/polybar/config$HOME/.config/polybar/config
-
-r
,
--reload
¶
Reload the application when the config file has been modified
-
-d
,
--dump
=PARAM
¶ Print the value of the specified parameter PARAM in bar section and exit
-
-m
,
--list-monitors
¶
Print list of available monitors and exit
If some monitors are cloned, this will exclude all but one of them
-
-M
,
--list-all-monitors
¶
Print list of available monitors and exit
This will also include all cloned monitors.
-
-w
,
--print-wmname
¶
Print the generated WM_NAME and exit
-
-s
,
--stdout
¶
Output the data to stdout instead of drawing it to the X window
-
-p
,
--png
=FILE
¶ Save png snapshot to FILE after running for 3 seconds
AUTHOR¶
REPORTING BUGS¶
Report issues on GitHub <https://github.com/polybar/polybar>
SEE ALSO¶
polybar(5)¶
Description¶
The polybar configuration file defines the behavior and look of polybar. It uses a variant of the INI file format. The exact syntax is described below but first a small snippet to get familiar with the syntax:
[section_name]
; A comment
# Another comment
background = #ff992a
width = 90%
monitor = HDMI-0
screenchange-reload = false
; Use double quotes if you want to keep the surrounding space.
text = " Some text "
When started polybar
will search for the config file in one of several
places in the following order:
- If the
-c
or--config
command line argument is specified, it will use the path given there. - If the environment variable
XDG_CONFIG_HOME
is set it will use$XDG_CONFIG_HOME/polybar/config
- If the environment variable
HOME
is set it will use$HOME/.config/polybar/config
Syntax¶
The entire config is line-based so everything is constrained to a single line. This means there are no multiline values or other multiline constructs (except for sections). Each line has one of four types:
- Empty
- Comment
- Section Header
- Key
Spaces at the beginning and end of each line will be ignored.
Note
In this context “spaces” include the regular space character as well as the
tab character and any other character for which isspace(3) returns
true
(e.g. \r
).
Any line that doesn’t fit into one of these four types is a syntax error.
Note
It is recommended that section header names and key names only use
alphanumeric characters as well as dashes (-
), underscores (_
) and
forward slashes (/
).
In practice all characters are allowed except for spaces and any of these:
"'=;#[](){}:.$\%
Section Headers¶
Sections are used to group config options together. For example each module is defined in its own section.
A section is defined by placing the name of the section in square brackets
([
and ]
). For example:
[module/wm]
This declares a section with the name module/wm
and all keys defined after
this line will belong to that section until a new section is declared.
Warning
The first non-empty and non-comment line in the main config file must be a section header. It cannot be a key because that key would not belong to any section.
Note
The following section names are reserved and cannot be used inside the config:
self
, root
, and BAR
.
Keys¶
Keys are defined by assigning a value to a name like this:
name = value
This assigns value
to the key name
in whatever section this line is in.
Key names need to be unique per section.
If the value is enclosed by double-quotes ("
), the quotes will be ignored.
So the following still assigns value
to name
:
name = "value"
Spaces around the equal sign are ignored, the following are all equivalent:
name=value
name = value
name = value
Because spaces at the beginning and end of the line are also ignored, if you want your value to begin and/or end with a space, the value needs to be enclosed in double-quotes:
name = " value "
Here name
has a leading and trailing whitespace.
Empty Lines & Comments¶
Empty lines and comment lines are ignored when reading the config file, they do
not affect polybar’s behavior. Comment lines start with either the ;
or the
#
character.
Note
Inline comments are not supported. For example the following line does not end
with a comment, they value of name
is actually set to value ; comment
:
name = value ; comment
SEE ALSO¶
Packaging Polybar¶
Do you want to package polybar for a distro? Great! Read this page to get started.
First Steps¶
Before you get started, have a look at the Packaging Label on our GitHub repo and Repology to see if polybar is already packaged for that distro or if there are efforts to do so.
Even if a package already exists, it might still make sense for you to package polybar in some cases. Some of these cases are:
- The existing package is out-of-date and the packager is no longer able/willing to continue maintaining the package (or they are simply not reachable anymore).
- The existing package exist in some non-official repository and you are able to introduce the package into the official package repository for the distro/package manager. For example if there is a PPA providing polybar for Ubuntu and you can add polybar to the official Ubuntu repositories, please do :)
The list above is not exhaustive, if you are unsure, feel free to ask in a new GitHub issue or on Gitter. Please also ask if you run into any polybar related issues while packaging.
Packaging¶
If you haven’t already, carefully read the Compiling wiki page to make sure you fully understand all the dependencies involved and how to build polybar manually.
We can’t really tell you how to create a package for your distro, you need to figure that out yourself. But we can give you some guidance on building polybar for a package
Gathering the Source Code¶
Unless you are creating a package that tracks the master
branch, don’t clone
the git repository. We provide a tarball with all the required source code on
our Release Page, use that in
your build.
Configuring and Compiling¶
Note
Do not use the build.sh
script for building polybar for your package. The
usage and flags of the script may change without notice and we don’t consider
that a breaking change.
You can mostly follow the instructions on the wiki for how to
compile polybar, but there are some additional cmake
arguments you might
want to use:
-DCMAKE_BUILD_TYPE=Release
: As of writing this is already the default, but use it just to be on the safe side.-DCMAKE_INSTALL_PREFIX=/usr
: Without this all the polybar files will be installed under/usr/local
. However, for packages it is often recommended they directly install to/usr
. So this flag will install polybar to/usr/bin/polybar
instead of/usr/local/bin/polybar
. The packaging guidelines for your distro may disagree with this, in that case be sure to follow your distro’s guidelines.
Instead of sudo make install
, you will most likely want to use
DESTDIR=<dir> make install
. That way the files will be installed into
<dir>
instead of your filesystem root.
Finishing Up¶
Finally, subscribe to our GitHub thread for package maintainers to get notified about new releases and changes to how polybar is built. If you want to, you can also open a PR to add your package to the Getting Started section of our README.
Thank you very much for maintaining a polybar package! 🎉
Release Workflow¶
We try to follow Semantic Versioning in this project.
Patch releases (e.g. 3.3.X
) contain only bug fixes. Minor releases (e.g.
3.X.0
) can have backwards-compatible features. And major releases (
X.0.0
) can introduce incompatible changes.
Note
This document replaces the “Release Guidelines” on the wiki that we used between 3.2.0 and 3.4.3. Starting with 3.5.0, we will follow the workflow described here to publish releases.
Polybar uses the OneFlow branching model for publishing new releases and introducing hotfixes.
The way we accept code from contributors does not change: Contributors fork polybar, commit their changes to a new branch and open a PR to get that branch merged. After reviewing and approving the changes, a maintainer “merges” the PR. “Merging” is done in the GitHub UI by either rebasing or squashing the changes. Regular merging is disabled because we do not want merge a merge commit for every PR.
This document is mainly concerned with how to properly release a new version of polybar. For that reason this might not be of interest to you, if you are not a maintainer, but feel free to read on anyway.
Drafting a new Release¶
There a two processes for how to draft a new release. The process for major and minor versions is the same as they both are “regular” releases. Patch releases are triggered by bugfixes that cannot wait until the next regular release and have a slightly different workflow.
Regular Releases (Major, Minor)¶
Regular releases are created once we find that master
is in a stable state
and that there are enough new features to justify a new release.
A release branch release/X.Y.0
is branched off of a commit on master
that contains all the features we want in the release, this branch is pushed to
the official repository.
For example for version 3.5.0
the branch release/3.5.0
would be created:
git checkout -b release/3.5.0 <commit>
The release branch should typically only exist for at most a few days.
Hotfix Releases (Patch)¶
A hotfix release is created whenever we receive a fix for a bug that we believe should be released immediately instead of it only being part of the next regular release. Generally any bugfix qualifies, but it is up to the maintainers to decide whether a hotfix release should be created.
The hotfix release branch hotfix/X.Y.Z
is created by branching off at the
previous release tag (X.Y.Z-1
).
For example, if the latest version is 3.5.2
, the next hotfix will be on
branch hotfix/3.5.3
:
git checkout -b hotfix/3.5.3 3.5.2
Since the PRs for such bugfixes are often not created by maintainers, they will
often not be based on the latest release tag, but just be branched off
master
because contributors don’t necessarily know about this branching
model and also may well not know whether a hotfix will be created for a certain
bugfix.
In case a PR containing a bugfix that is destined for a patch release is not branched off the previous release, a maintainer creates the proper release branch and cherry-picks the bugfix commits.
Note
Alternatively, the contributor can also git rebase --onto
to base the
branch off the previous release tag. However, in most cases it makes sense for
a maintainer to create the release branch since they will also need to add a
Release Commit to it.
Once the release branch is created and contains the right commits, the maintainer should follow Publishing a new Release to finish this patch release.
If multiple bugfixes are submitted in close succession, they can all be cherry-picked onto the same patch release branch to not create many individual release with only a single fix. The maintainer can also decide to leave the release branch for this patch release open for a week in order to possibly combine multiple bugfixes into a single release.
Publishing a new Release¶
The process for publishing a release is the same for all release types. It goes as follows:
- A Release commit is added to the tip of the release branch.
- A draft PR is opened for the release branch. This PR MUST NOT be merged in GitHub’s interface, it is only here for review, merging happens at the commandline.
- After approval, the GitHub release publishing tool is used to publish the release and tag the tip of the release branch (the release commit).
- After the tag is created, the release branch is manually merged into
master
. Here it is vitally important that the history of the release branch does not change and so we usegit merge
. We do it manually because usinggit merge
is disabled on PRs.
git checkout master
git merge <release-branch>
git push origin
- After the tag is created, the release branch can be deleted with
git push origin :<release-branch>
. - Work through the After-Release Checklist.
Here <release-branch>
is either a release/X.Y.0
branch or a
hotfix/X.Y.Z
branch.
Release Commit¶
When merging, a release commit must be at the tip of the release branch.
The release commit needs to update the version number in:
version.txt
The commit message contains the Changelog for this release.
Changelog¶
Each release should come with a changelog briefly explaining what has changed for the user. It should generally be separated into ‘Deprecations’, ‘Features’, and ‘Fixes’, with ‘Breaking Changes’ listed separately at the top.
See old releases for how to format the changelog.
Since major releases generally break backwards compatibility in some way, their changelog should also prominently feature precisely what breaking changes were introduced. If suitable, maybe even separate documentation dedicated to the migration should be written.
After-Release Checklist¶
- Make sure all the new functionality is documented on the wiki
- Mark deprecated features appropriately (see Deprecations)
- Remove all unreleased notes from the wiki (not for patch releases)
- Inform packagers of new release in #1971. Mention any dependency changes and any changes to the build workflow. Also mention any new files are created by the installation.
- Create a source archive named
polybar-<version>.tar
. The repository contains a script that automates this:
./common/release-archive.sh <version>
- Update the github release with a download section that contains a link to
polybar-<version>.tar
and its sha256. - Create a PR that updates the AUR
PKGBUILD
files for thepolybar
andpolybar-git
packages (push after the.tar
file was created).
Deprecations¶
If any publicly facing part of polybar is being deprecated, it should be marked as such in the code, through warnings/errors in the log, and by comments in the wiki. Every deprecated functionality is kept until the next major release and removed there, unless it has not been deprecated in a minor release before.
Getting Help¶
- Polybar Wiki
- Gitter
- /r/polybar on reddit
#polybar
onchat.freenode.net