A modular framework for interactive bash plugin management
without overcomplicating your .bashrc
You can install bics
locally by running the following one-liner
bash <(curl -sS https://raw.githubusercontent.com/bahamas10/bics/master/bics) init
Running this again after bics
is installed will upgrade bics
to the
latest version from GitHub.
After installing bics
, add the following line to your .bashrc
file
. ~/.bics/bics
...and then exec bash to load the plugins
$ exec bash
$ bics list
> test-plugin
As you can see, one plugin has been installed automatically, test-plugin
. You can
view its source with:
$ cat ~/.bics/plugins/test-plugin/*.bash
# add code here
This plugin doesn't do much, but it shows how to add plugins for use by bics
.
bics
will search ~/.bics/plugin/*/*.bash
and source every file matching that glob
To get started, you can delete that plugin by running
bics remove test-plugin
...or achieve the same thing manually by running
rm -r ~/.bics/plugins/test-plugin
Now, when you list the installed plugins you'll see nothing
$ bics ls
$
Notice that ls
is an alias for list
Plugins are installed to ~/.bics/plugins
as directories that contain 1 or more
.bash
files. Let's install a simple plugin that is on GitHub.
To install this plugin we run:
$ bics install https://github.com/bahamas10/bash-cdstack
Cloning into 'bash-cdstack'...
remote: Counting objects: 8, done.
remote: Compressing objects: 100% (6/6), done.
remote: Total 8 (delta 2), reused 8 (delta 2)
Unpacking objects: 100% (8/8), done.
This is a shorthand way of running:
cd ~/.bics/plugins && git clone https://github.com/bahamas10/bash-cdstack
And that's it! The plugin is installed, you can start using it by running:
exec bash
... to reload the bash environment
You can list installed plugins to see that cdstack
is present
$ bics ls
> bash-cdstack
See Managing Plugins for more information about storing plugins in a dotfiles repository as submodules
Run the following to get help on the command line
$ bics help
usage: bics [command] [args...]
(v0.0.8)
...
You can also run bics help
on any plugin to view it's documentation in
your PAGER
(defaults to less
).
$ bics help bash-cdstack
This will open $PAGER
on the README.md
file in the repository. bics
scans for files that look like documentation and opens the first one it
finds, the order is:
{*.txt,*.md,readme,ReadMe,README}
So if you create a plugin and would like to include a help text specifically
for the command line, create a .txt
file
Here is a list of plugins Dave wrote for bics:
Creating a plugin is meant to be simple and easy. At the core, a plugin needs
to be a directory with 1 or more .bash
files that will be sourced upon bash's
execution. Take a look at the test-plugin
directory that is created when
bics
is installed to see how a simple plugin looks.
Ideally, plugins will each have their own repository here on GitHub, and can be stored in a users dotfiles repository as git submodules.
An example real-world plugin can be seen here https://github.com/bahamas10/bash-cdstack
You can store your plugins as git submodules stored in a dotfiles repo. An
example can be seen here, specifically the bics-plugins
directory.
https://github.com/bahamas10/dotfiles
This commit shows an example git submodule added, and logic to install bics
initially and symlink the plugins directory accordingly.
https://github.com/bahamas10/dotfiles/commit/50cd7a236069cf98eacf170b2d6629e814075fb8
NOTE: if you use this method, bics install
and bics update
will not
work as expected, you'll need to manage the plugins manually with git
.
bics
tries not to clutter up your namespace or clobber variables in your
shell. Below is a list of all variables/functions/aliases created by bics
BICS_VERSION
- the version ofbics
when it was sourcedBICS_SOURCED
- an array of relative filenames that were sourced bybics
example:
$ echo "$BICS_VERSION"
v0.0.5
$ printf '%s\n' "${BICS_SOURCED[@]}"
/home/dave/.bics/plugins/bash-analysis/analysis.bash
/home/dave/.bics/plugins/bash-cdstack/cdstack.bash
/home/dave/.bics/plugins/bash-dvorak/dvorak.bash
None.
bics
- aliased to~/.bics/bics
_bics
- used for bash completion_
- anonymous function used (and cleared) bybics
A standard convention for plugins is to use _
as a throwaway function name to
allow for local variables that don't clutter up the default namespace. A
similar technique is used in JavaScript to create anonymous, self-executing
functions to avoid creating global variables.
example
_() {
local i=0
local foo=bar
echo "$foo" > "/tmp/something.$i"
}
_
In this example, i
and foo
are not made global. The only thing made global
is the _
function
bics
will unset _
(the function) after it has finished loading plugins
Provided for...
bics
You can update all plugins, or a specific plugin by running
$ bics update [name]
If name
is empty, all plugins are updated
You can update bics
itself at anytime by running
$ bics self-upgrade
> getting source from https://githubusercontent.com/bahamas10/bics/raw/master/bics... done
bics
doesn't require any external programs to source plugins that are already
installed, however some of the extra features require various programs to be
installed.
Required for bics install
and bics update
. The only operations done are
git clone
and git pull
respectively.
Required for bics help
and bics init
to colorize output - will silently fail
if not found.
Any code submitted should pass the syntax check:
$ make check
expand bics | awk 'length($0) > 80 { exit(1); }'
./bics -h | expand | awk 'length($0) > 80 { exit(1); }'
shellcheck bics
Bash style guide: https://github.com/bahamas10/bash-style-guide
MIT License