Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/bahamas10/bics
A modular framework for bash plugin management
https://github.com/bahamas10/bics
Last synced: 2 months ago
JSON representation
A modular framework for bash plugin management
- Host: GitHub
- URL: https://github.com/bahamas10/bics
- Owner: bahamas10
- Created: 2014-03-25T04:53:54.000Z (almost 11 years ago)
- Default Branch: master
- Last Pushed: 2024-08-02T15:59:06.000Z (5 months ago)
- Last Synced: 2024-08-02T17:46:41.994Z (5 months ago)
- Language: Shell
- Size: 13.7 KB
- Stars: 8
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
bics - Bash Interactive Configuration System
============================================
A modular framework for interactive bash plugin management
without overcomplicating your `.bashrc`
Installation
------------
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.
Getting Started
---------------
### Setup
After installing `bics`, add the following line to your `.bashrc` file
``` bash
. ~/.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`
### Installing Plugins
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](#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:
- [bash-cdstack](https://www.github.com/bahamas10/bash-cdstack)
- [bash-analysis](https://www.github.com/bahamas10/bash-analysis)
- [bash-dvorak](https://www.github.com/bahamas10/bash-dvorak)
- [bash-interactivity](https://www.github.com/bahamas10/bash-interactivity)
- [bash-path](https://www.github.com/bahamas10/bash-path)
- [tabstop](https://www.github.com/bahamas10/tabstop)
Plugins
-------
### Creating a Plugin
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
### Managing Plugins
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`.
Environment
-----------
`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`
### Global Variables
- `BICS_VERSION` - the version of `bics` when it was sourced
- `BICS_SOURCED` - an array of relative filenames that were sourced by `bics`
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
### Exported Variables
None.
### Aliases
- `bics` - aliased to `~/.bics/bics`
### Functions
- `_bics` - used for bash completion
- `_` - anonymous function used (and cleared) by `bics`
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
``` bash
_() {
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
### Bash Completion
Provided for...
- `bics`
Updates
-------
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
Dependencies
------------
`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.
### `git`
Required for `bics install` and `bics update`. The only operations done are
`git clone` and `git pull` respectively.
### `tput`
Required for `bics help` and `bics init` to colorize output - will silently fail
if not found.
Pull Requests
-------------
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
License
-------
MIT License