Bash Packages Are Nifty


Using the bpan CLI tool:

$ bpan search utils
$ bpan install somebody/path-utils
$ bpan new /path/to/my-project
$ bpan add getopt-bash ingydotnet/json-bash

Use the bpan Bash library in your Bash code:

#!/usr/bin/env bash

source "$MY_PROJECT_ROOT/.bpan/lib/bpan.bash" --

bpan:source bashplus=0.1.0
bpan:source bpan-org/getopt
bpan:source github:ingydotnet/json

Publish your Bash packages:

$ bpan register .
$ bpan publish .


BPAN is the "Missing Bash Package Manager".

It does 3 big things for you and your Bash code:


BPAN, works and is tested under the following shells: bash, zsh, fish, ksh, mksh, tcsh, ash, dash, posh and sh.

  1. Clone the BPAN repo:
   git clone https://github.com/bpan-org/bpan "$HOME/.bpan"
  1. Source the BPAN .rc file to use bpan immediately:
   source "$HOME/.bpan/.rc"

For ksh, mksh, ash, dash, posh and sh: set BPAN_ROOT first, and use . instead of source:

   BPAN_ROOT=$HOME/.bpan/.rc . "$HOME/.bpan/.rc"
  1. Add the command in step 2 to your shell's startup file ($HOME/.bashrc, etc).

NOTE: $HOME/.bpan/ can be changed above to any other location that you wish to install BPAN.


BPAN needs just a few very common things to work:

Using the bpan CLI

The bpan command has 2 major roles:

Commands are grouped into 3 categories:

Start with bpan --help to get the basic usage info.

Documentation can be read with man bpan.

Using BPAN in a Project

BPAN is intended to be used mostly in software projects that have Bash dependencies.

To create a new project from scratch (that uses BPAN):

bpan new <dir-name>

To add BPAN support (.bpan/) to an existing project:

bpan init

To add a BPAN dependency to a project:

bpan add bashplus getopt-bash

To update the BPAN dependency files and generate man pages:

bpan update

System-wide BPAN Directory and File Layout

When you install packages system-wide with BPAN, things are stored under the $HOME/.bpan/local/ directory.

There are several $HOME/.bpan/local/ subdirectories where things get installed into:

Per-project BPAN Directory and File Layout

BPAN installs per-project things under a .bpan/ directory in the root of your project.

There are 3 main files to be aware of:

  1. ./.rc

    This file is responsible for defining and exporting MY_PROJECT_ROOT where MY_PROJECT is the name of your project. This environment variable is the key to bootstrapping BPAN and other things that your project will need. While not strictly necessary, it is highly recommended.

  2. ./.bpan/config

    This is your project's BPAN configuration file. It's where you make all of your configuration choices and list all the BPAN dependency packages.

  3. ./.bpan/lib/bpan.bash

    This is the file that you source in your programs to initialize the BPAN environment, with something like:

   source "$MY_PROJECT_ROOT/.bpan/lib/bpan.bash" --
   # or:
   export PATH=$MY_PROJECT_ROOT/.bpan/lib:$PATH
   source bpan --

This will initialize all the settings that you have chosen for your project, and autoload all the BPAN packages that you have configured.

Additionally there are 3 possible .bpan/ sub-directories:

This is where your per-project dependency package assets are installed to.

Project .bpan/config Configuration

A typical BPAN config file looks like:

api-version = 1

name = thinger-bash
version = 0.1.0
title = Do the thing
license = MIT
copyright = 2022

repo = https://github.com/$author.github/$package.name
branch = main
site = $package.repo
bug = $package.repo/issues/
irc = irc.libera.chat/bpan

name = Ingy döt Net
email = ingy@ingy.net
github = ingydotnet
twitter = ingydotnet
irc = ingy@irc.libera.chat
matrix = @ingy:yaml.io
site = https://github.com/$author.github

github = ingydotnet

[require "package"]
bashplus = 0.1.0+
getopt-bash = 0.1.0+

[require "command"]
bash = 4.4+
git = 2.25+
perl = 5.28.3+

package = bashplus
package = getopt-bash
file = License
file = Makefile
file = ReadMe.md doc/thinger.md
file = test/init
file = test/00-shellcheck.t
man1 = doc/thinger.md

BPAN Sources

Currently, all BPAN installable packages are specific commits in public Git repositories.

The BPAN index lives here: https://github.com/bpan-org/bpan-index

Copyright and License

Copyright 2022 by Ingy döt Net

This is free software, licensed under:

The MIT (X11) License