birb.1

.TH birb 1 "15.5.2023"
.SH NAME
birb \- CLI package manager for BirbOS
.SH SYNOPSIS
\fBbirb\fP [OPTIONS...] [ARGUMENTS...] [PACKAGE(s)...]
.SH DESCRIPTION
\fBbirb\fP is a package manager specifically written to be used in BirbOS. It installs packages into separate fakeroots and then uses GNU stow to install those fakeroots to the system root. \fBbirb\fP packages are simple shell scripts called seeds.
.SH OPTIONS
.TP
All non-matching arguments are interpreted as package names. This means that running '\fBbirb \fP\fIpackage\fP' would attempt to install the given package.
.TP
\fB--help\fP
Output a usage message and exit
.TP
\fB--download \fIPACKAGE(s)\fP
Download the source tarball for the given package
.TP
\fB-i, --install [--test] [--overwrite] \fIPACKAGE(s)\fP
Install given package(s) to the filesystem. If --test is set, run any tests that the package might contain

If you come across a package that wants to overwrite something, you can use the --overwrite flag to give \fBbirb\fP the permission to delete files from root directories like /usr to attempt solving conflicts. This however can in some cases result in a partially broken system if used carelessly.
.TP
\fB-u, --uninstall \fIPACKAGE(s)\fP
Uninstall given package(s) from the filesystem
.TP
\fB--depclean\fP
Delete orphan packages that were installed as a dependency for some package that isn't installed anymore
.TP
\fB--relink \fIPACKAGE(s)\fP
Re-create symlinks to the package fakeroots. This is useful in situations where you have accidentally removed something from /usr/bin for example. Simply re-applying the symlinks also saves you the compiling time required to fully reinstall the package.
.TP
\fB-s, --search\fP
Search for packages by name
.TP
\fB-b, --browse\fP
Browse packages and their descriptions with \fBfzf\fP. This option needs the \fBfzf\fP package to be installed.
.TP
\fB--source [query|stable|testing]\fP
Change or query the repository source branch. Birb will sync the repositories after switching the branch

The \fBquery\fP option returns the current branch in use. You can also see the git branch names from git output.

The \fBstable\fP branch contains (in theory at least) stable packages that have been somewhat proven to compile and install properly (and might even run properly too).

The \fBtesting\fP branch is basically a raw feed of commits with no quarantee of working packages. It is more up-to-date than the stable branch, but carries the risk of breaking your installation or causing some other undefined trouble.
.TP
\fB--sync [--force]\fP
Sync package repositories. If there are any issues with syncing, you can try if --force fixes the problem. The force flag hard resets the package repositories and throws any local uncommited changes away
.TP
\fB--list-installed\fP
List all currently installed packages
.TP
\fB--update\fP
Find all packages that are out-of-date and attempt to update them. In most cases you should be able to cancel the update after you have already started it and \fBbirb\fP should be able to restore things back, but if anything goes wrong, you can find (usually) a backup of the package fakeroot from /var/backup/birb/fakeroot_backups.
.TP
\fB--restore \fIPACKAGE\fP
Restore a fakeroot backup created by a failed update. This option will cause the package to be uninstalled for a moment, so be careful with using this option if the package is important to the system stability.
.TP
\fB--upgrade [--debug|--test]\fP
Update the birb package manager.

If --debug is set, build the C++ parts of birb with debug flags enabled and skip PGO and LTO.

If --test is set, compile \fBbirb\fP like normal with all optimizations enabled, but on top of that compile tests and run them. If the tests fail, cancel the upgrade.
.TP
\fB--repair\fP
Attempt to recover a broken system (due to missing packages) by using the package database as a ground truth for what should be installed on the system. This way we can reinstall packages that have their files missing, but the system still thinks that the package is already installed.
.SH FILES
.TP
\fC/etc/birb.conf\fR
The main configuration file for \fBbirb\fP. The file is in shell script form and gets sourced when \fBbirb\fP is run.
.TP
\fC/etc/birb-sources.conf\fR
Configuration file for repository sources. Repositories are listed in the file formatted with the format repository-name;source-url;repository-directory-on-disk (see the default file for an example). The order of the lines is important, since the repositories are checked in the order that they are listed in the file.
.SH TROUBLESHOOTING
.TP
\fBMissing /etc/birb-sources.conf\fP
In case of an error indicating the that file \fB/etc/birb-sources.conf\fP is missing, you can recover it by either creating a new one manually with atleast one valid repository, or by navigating to \fB/var/cache/distfiles/birb\fP and running the commands \fBmake\fP and \fBmake install\fP as the root user. This should compile a non-optimized debug build and install any missing files back to their places. When the problem is solved, you can compile and install the optimized binaries by running the command \fBbirb --upgrade\fP as the root user.
.TP
\fBI accidentally deleted the birb sources from /var/cache/distfiles/birb
If you still have birb installed, you can run \fBbirb --upgrade\fP to fix the situation. The upgrade process will look for the source code directory and clone the source code from git if it doesn't exist.

If birb is unavailable, you can manually clone the birb github repository at https://github.com/Toasterbirb/birb to /var/cache/distfiles/birb and then install birb by running \fBmake\fP and \fBmake install\fP in the repo directory as the root user. If the installation was successful, you can compile and install the optimized binaries by running \fBmake release\fP and \fBmake install\fP as the root user, or by simply running \fBbirb --upgrade\fP.
.SH "SEE ALSO"
stow(8)
.SH BUGS
Please report any bug findings here https://github.com/Toasterbirb/birb/issues