Run byobu-janitor safely after a Byobu upgrade

You will use the installed byobu-janitor to refresh Byobu's runtime state after an upgrade, seed any missing per-user files, and understand when it will do nothing. This guide targets Ubuntu's byobu package 6.11-0ubuntu1.1, which is the installed version here. Allow about five minutes. You need a normal user account with a working home directory; most steps do not need sudo.

1. Check the installed command and package

The manpage describes byobu-janitor as a no-argument cleanup script. Check that the command comes from the package you expect, then record the package version.

$ command -v byobu-janitor
/usr/bin/byobu-janitor
$ dpkg-query -W -f='${Package} ${Version}\n' byobu
byobu 6.11-0ubuntu1.1

Your version and path may differ. The installed script, rather than the short manpage, is the useful source for the upgrade actions. In this release, the script accepts --force even though the manpage synopsis only shows the command without arguments.

2. Understand the ordinary run

Run it without arguments when an upgrade has already left Byobu's reload flag in place. The script first removes its backend cache marker and metadata-availability markers. If the reload flag is absent, it then exits without seeding or changing the rest of your configuration. This makes an ordinary run suitable as a quick post-upgrade check.

$ byobu-janitor
$ printf 'exit status: %s\n' "$?"
exit status: 0

There is normally no output on success. The command does not print a report, so a zero exit status is the verification signal.

CHECKPOINT: If you only wanted the routine cleanup, stop here. Your next step is needed only when the reload flag is missing or you want first-run files seeded.

3. Decide whether forcing the repair is appropriate

With --force, the script proceeds through its configuration work even when $BYOBU_RUN_DIR/reload-required does not exist. It creates the Byobu configuration directory if needed, using $XDG_CONFIG_HOME/byobu when that variable is set and otherwise $HOME/.config/byobu. An existing legacy $HOME/.byobu directory is preferred by the installed directory helper.

Forcing is a state-changing operation. It can create files, remove obsolete configuration and, for an old upgrade path, append a Byobu prompt hook to an otherwise stock writable $HOME/.bashrc. Read the script's target directories before using it on a managed account.

$ printf 'HOME=%s\nXDG_CONFIG_HOME=%s\nBYOBU_CONFIG_DIR=%s\n' \\
    "$HOME" "${XDG_CONFIG_HOME:-unset}" "${BYOBU_CONFIG_DIR:-unset}"
HOME=/home/alice
XDG_CONFIG_HOME=unset
BYOBU_CONFIG_DIR=unset

4. Run the forced initialisation

Only do this as the user whose Byobu files you intend to repair. Do not use sudo: the script reads $HOME/.byoburc and writes user-owned configuration. Running it through sudo can create root-owned files or make your own configuration unwritable.

$ byobu-janitor --force
$ printf 'exit status: %s\n' "$?"
exit status: 0

On a new or incomplete setup, this can create the colour setting files, date and time settings, profile files, keybinding files, window files, backend selection, Screen and tmux stubs, status files and prompt file under the Byobu configuration directory. Existing readable files are generally preserved rather than replaced.

5. Verify what was created

Resolve the directory in the same shell and list it. The exact list depends on whether you had Byobu configuration already.

$ BYOBU_CONFIG_DIR="${BYOBU_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/byobu}"
$ find "$BYOBU_CONFIG_DIR" -maxdepth 1 -type f -printf '%f\n' | sort
.screenrc
.tmux.conf
backend
color
color.tmux
datetime.tmux
keybindings
keybindings.tmux
profile
profile.tmux
prompt
status
statusrc
windows
windows.tmux

If the directory is not writable, the script prints an error naming it and exits non-zero. Fix ownership or permissions as the account owner, then rerun. Do not solve a user-directory problem by making the directory broadly writable.

6. Check the reload path after an upgrade

Package or Byobu upgrade logic can create $BYOBU_RUN_DIR/reload-required. A normal invocation removes that flag after the upgrade work has been performed. If you need to inspect it before running the command, find the runtime directory from the current shell rather than guessing a permanent path.

$ printf 'runtime directory: %s\n' "${BYOBU_RUN_DIR:-not set in this shell}"
runtime directory: not set in this shell
$ byobu-janitor
$ test ! -e "${BYOBU_RUN_DIR:-$HOME/.cache/byobu}/reload-required" && echo 'reload flag cleared or was absent'
reload flag cleared or was absent

The script also removes an older reload flag at /var/run/screen/S-$USER/byobu.reload-required. That path is relevant to older Screen-based setups. The current command does not promise that a running Byobu session will visibly redraw immediately; start a new session or restart the affected session if its status remains stale.

7. Know what cleanup may remove

The script removes old Byobu runtime cache markers, the two metadata-availability markers, the obsolete ec2_rates configuration file and old cost-status cache files. It may also remove the old status and statusrc files when status lacks the expected screen_upper_left= setting, and converts selected legacy window entries in place.

These are upgrade migrations, not a general backup mechanism. Before forcing an unfamiliar or heavily customised setup, copy the configuration directory somewhere private.

$ BYOBU_CONFIG_DIR="${BYOBU_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/byobu}"
$ cp -a "$BYOBU_CONFIG_DIR" "$BYOBU_CONFIG_DIR.before-janitor"
$ byobu-janitor --force

There is no built-in undo command. To recover a changed user configuration, exit Byobu, remove the damaged configuration directory only after checking its contents, and restore the backup with the same ownership and permissions. A safer alternative is to restore individual files from the backup.