Make Bash Great Again!

An elegant framework to manage commands, completions, dotfiles for bash players.

English | 中文

Features

• Manage collections of dotfiles in one place. Using YAML file to manage soft-links via dotbot.
• Manage shell scripts, completions, aliases by modules. Support custom modules.
• Easy to share and reuse executable files, sub commands, configs and modules by repo. Read one.share.
• Support custom repo and multiple repos. Managed by ONE_REPOS.
• Manage commands under your own scope. Like a <cmd> to invoke command that no worry about duplicated in PATH. Read the ONE_SUB Commands.
• Support custom one.bash. Read ONE_CONF.
• Support bash-it. You can use one commands to manage bash-it's aliases/completions/plugins. Read bash-it.md.
• Support Fig. Read fig.md.

Environments

• ✅ iTerm2
• ✅ Terminal.app
• ✅ MacOS Intel Arch
• ✅ MacOS ARM Arch
• ✅ Linux/Unix system
• 🚫 Windows system
• 🚫 Zsh. This project is just for Bash players. Zsh players should use Oh My Zsh.

CI Status

• develop branch:

Versions

See tags. The versions follows the rules of SemVer 2.0.0.

Dependencies

Requires

• GNU Bash 4.4 or 5.0+
• python3
• perl 5
• git

Inspired By

one.bash is inspired by sub and bash-it.

• sub: A delicious way to organize programs created by basecamp. But no more maintained.
• bash-it: A community Bash framework.

Who uses one.bash

See https://github.com/topics/one-bash

( You can add one-bash topic in your Github project for sharing. )

Installation

# Set the directory for download one.bash
ONE_DIR=~/.one.bash
git clone --depth 1 https://github.com/one-bash/one.bash.git $ONE_DIR
# Note: you should ensure /usr/local/bin/ is in environment variable PATH
sudo ln -s "$ONE_DIR/bin/one" /usr/local/bin/one

# Install Dependencies
one dep install

# Add one.bash to your bashrc. Or you can add the result of "one --bashrc" to bashrc by manual.
echo '' >> ~/.bashrc
one --bashrc >> ~/.bashrc

Configuration

ONE_CONF

ONE_CONF is the filepath of one.bash configuration. The file is not required. one.bash has default config.

ONE_CONF=${XDG_CONFIG_HOME:-$HOME/.config}/one.bash/one.config.bash
mkdir -p "$(dirname "$ONE_CONF")"

# Create your dotfiles on any path.
DOTFILES_DIR=$HOME/.dotfiles
mkdir -p "$DOTFILES_DIR"

cat <<-EOF >"$ONE_CONF"
DOTFILES_DIR="$DOTFILES_DIR"

ONE_DEBUG=false
ONE_REPOS=(
  "$DOTFILES_DIR"
)
ONE_LINKS_CONF() {
  case "$1" in
    *) echo "$DOTFILES_DIR"/one.links.yaml ;;
  esac
}
EOF

. "$ONE_CONF"

For more ONE_CONF options and documents, Please read ./one.config.default.bash.

You can use one config <key>=<val> set config option. (function and array are not supported)

And one config <key> to query config option.

ONE_LINKS_CONF

ONE_LINKS_CONF is a bash function that returns a filepath of dotbot config. Defaults to empty.

This function receives two parameters: OS (uname -s), Arch (uname -m). It is used for managing different dotbot configs for different environments (such as MacOS and Linux).

# User should print the path of ONE_LINKS_CONF file
# @param os   $(uname -s)
# @param arch $(uname -m)
ONE_LINKS_CONF() {
  local os=$1
  local arch=$2
  case "$os_$arch" in
    Darwin_arm64) echo "$DOTFILES_DIR"/links/macos_arm.yaml ;;
    Darwin_amd64) echo "$DOTFILES_DIR"/links/macos_intel.yaml ;;
    Linux*) echo "$DOTFILES_DIR"/links/linux.yaml ;;
  esac
}

The dotbot is a tool to manage symbol links of dotfiles and any other files. It is a part of one.bash. You can use it to create symbol links to any files.

There is a dotbot config template in one.share. You can copy one.links.example.yaml to your directory.

cp "$ONE_SHARE_DIR"/one.links.example.yaml "$DOTFILES_DIR"/one.links.yaml
# Edit the one.links.yaml for your demand
$EDITOR "$DOTFILES_DIR"/one.links.yaml

Invoke one link to create symbol links based on ONE_LINKS_CONF file. Notice: Do not invoke one link with sudo.

Invoke one unlink to remove all symbol links based on ONE_LINKS_CONF file.

You can use dotbot plugins for more directives. See https://github.com/anishathalye/dotbot/wiki/Plugins

Usage

If ONE_SHARE_ENABLE is true, invoke $ONE_SHARE_ENABLE/recommended-modules to enable recommended modules in one.share.

If ONE_BASH_IT_ENABLE is true, invoke one completion enable aliases.completion.

ONE Commands

The one command is used to manage one.bash modules, one.config, and dependencies.

Invoke one to show usage of it.

Usage: one [<CMD>]                 Run one command
       one subs [<SUB_CMD>]        Run ONE_SUB command
       one help [<CMD>]            Show the usage of one command
       one help-sub [<SUB_CMD>]    Show the usage of ONE_SUB command
       one [--bashrc]              Print one.bash entry codes for bashrc
       one [-h|--help]             Show the usage of one

Desc: An elegant framework to manage commands, completions, dotfiles for terminal players.
      https://github.com/one-bash/one.bash

Arguments:
  <CMD> the command of one
  <SUB_CMD> the command of ONE_SUB

It provides many commands defined in ./one-cmds/.

• one commands to list all commands.
• one help -a to list all usages of commands.
• one bin list to show all executable files in bin/ of each repo.
• one sub list to show all commands in sub/ of each repo.

Modules

one.bash uses modules to manage shell scripts.

User can use one commands to manage modules. Enable/Disable modules on your demand.

The modules have three types: alias, completion, plugin.

• All plugins are put in plugins/ of each repo.
• All completions are put in completions/ of each repo.
• All aliases are put in aliases/ of each repo.
• All enabled modules are symbol linked in $ONE_DIR/enabled/ directory.
  • one enabled list to view enabled modules.
  • one enabled backup to backup enabled modules to a file.
• Read one help <mod_type> for usages.
• one <mod_type> enable to enable modules.
• one <mod_type> disable to disable modules.
• one <mod_type> list to list modules.

one.share has provided many modules, configs, ONE_SUB commands, and bin commands.

It's suggested to move your shell codes to modules for management.

Read the Module document for details.

ONE_REPOS

one.bash is just a management framework. It does not contain any dotfiles, configs. The official repo one.share provides them to enhance shell.

one.bash enable one.share and bash-it by default. You can disable them by ONE_SHARE_ENABLE=false and ONE_BASH_IT_ENABLE=false in ONE_CONF.

You can create your own ONE repo. Read the Create Repo for details.

Just add repo's filepath to ONE_REPOS to enable the repo, or remove from ONE_REPOS to disable it.

Invoke one repo l to list ONE repos based on ONE_CONF.

ONE_SUB Commands

All executable files in sub/ of each repo could be invoked by one subs <cmd> or a <cmd> ($ONE_SUB <cmd>, ONE_SUB defaults to a, read the usage in ONE_CONF).

The sub/ path is not included in $PATH. So you cannot invoke ONE_SUB commands directly.

Read this document for more details.

Docs

• Bashrc Initialization Proces
• Project File Structure
• Advanced Usages
  • ONE Dependencies
  • ONE Functions
  • ONE_SUB Command
  • Fig
  • Bash-it

Suggestion, Bug Reporting, Contributing

Any comments and suggestions are always welcome.

Before open an issue/discussion/PR, You should search related issues/discussions/PRs first for avoiding to create duplicated links.

• For new feature request, open a discussion, describe your demand concisely and clearly.
• For new feature submit, open a PR, describe your demand and design concisely and clearly.
• For bug report, open an issue, describe the bug concisely and clearly.
• For bug fix, open a PR, concisely and clearly describe what you fixed.
• For question and suggestion, open a discussion.
• For anything not mentioned above, open a discussion.

Do not post duplicated and useless contents like +1, LOL. React to comments with emoji instead of.

Please communicate in English as much as possible.

Please read ./docs/CONTRIBUTING.md before make a Pull Request.

Copyright and License

Copyright 2022-2023 ADoyle (adoyle.h@gmail.com). Some Rights Reserved. The project is licensed under the Apache License Version 2.0.

Read the LICENSE file for the specific language governing permissions and limitations under the License.

Read the NOTICE file distributed with this work for additional information regarding copyright ownership.

Other Projects

• lobash: A modern, safe, powerful utility/library for Bash script development.
• Other shell projects created by me