🧈 ButterBash

A smooth, modular Bash configuration framework that makes your shell experience butter-smooth.

✨ Features

• Modular Design: Clean separation of concerns with individual files for aliases, functions, and configurations
• FZF Integration: Fuzzy finding for files and processes
• Git-Aware Prompt: Shows current branch in your prompt
• Extensive Aliases: Productivity shortcuts for common tasks
• Archive Extraction: Universal extract command for all archive types
• System Functions: Quick system info, colored man pages, and more
• Extension Ready: Works perfectly with ButterNotes for note-taking and todo management

📦 Installation

Recommended: Install via ButterScripts

The easiest way to install ButterBash is through the ButterScripts optional installer:

# Clone and run butterscripts installer
git clone https://justaguy.dev/drew/butterscripts.git
cd butterscripts/setup
./optional_tools.sh
# Select option 1: ButterBash ⭐

ButterBash is featured as the top option in ButterScripts' optional tools, providing seamless integration with the broader ecosystem of development tools.

Direct Install

1. Clone the repository:

git clone https://justaguy.dev/drew/butterbash.git
cd butterbash

2. Run the install script:

./install.sh

3. Reload your shell:

source ~/.bashrc

Important: ButterBash will backup your existing .bashrc and replace it with a modular configuration. This is the intended behavior for the full ButterBash experience.

🗂️ Structure

~/.config/bash/
├── aliases.bash        # Command shortcuts
├── prompt.bash         # Custom prompt with git branch
├── keybinds.bash       # Keyboard shortcuts
├── fzf.bash           # FZF configuration
├── zoxide.bash        # zoxide smarter-cd hook
└── functions/
    ├── system.bash    # System utilities
    └── utils.bash     # General utilities

🎯 Core Functions

Utility Functions

mkcd directory        # Create and enter directory
extract file.tar.gz   # Extract any archive type
backup file.txt       # Create timestamped backup
calc 2+2             # Quick calculations
sysinfo              # Display system information

⚙️ Configuration

Customization

Add your own customizations by creating files in ~/.config/bash/:

1. Create a new module: ~/.config/bash/custom.bash
2. It will be automatically loaded on next shell start

Local Overrides

For machine-specific settings, create ~/.bashrc.local:

# ~/.bashrc.local
export CUSTOM_VAR="value"
alias myalias="command"

# Add custom configurations here

Integration with Other Projects

ButterBash works seamlessly with other projects in the ButterScripts ecosystem:

• ButterScripts - Comprehensive setup scripts for Debian systems
• ButterNotes - Note-taking and todo management extension
• Integrates with terminal emulators like WezTerm
• Compatible with window managers (DWM, BSPWM, etc.)
• Works alongside other development tools and configurations

Want Note-Taking and Todo Management?

ButterBash focuses on shell configuration. For productivity features like notes and todos, install ButterNotes:

git clone https://justaguy.dev/drew/butternotes.git
cd butternotes && ./install.sh

ButterNotes works perfectly alongside ButterBash and adds:

• Intelligent note-taking with clipboard integration
• Todo management with markdown checkboxes
• Project organization with FZF
• Mobile sync compatibility
• Interactive terminal UI

🚀 Key Bindings

• Ctrl+L: Clear screen
• ↑/↓: Search command history
• Ctrl+R: Reverse history search (with FZF if available)

📋 Requirements

• Bash 4.0+
• install.sh pulls in the tools the config uses: fzf, ripgrep, eza, zoxide.
  • fzf - Fuzzy finder
  • ripgrep - Fast grep alternative
  • eza or exa - Modern ls replacement
  • zoxide - Smarter cd (z, zi)
• Optional clipboard integration (not pulled in automatically):
  • xclip (X11) / wl-clipboard (Wayland)

If you ever need to reinstall the core tools, there's a built-in helper:

install_tools  # reinstalls fzf and ripgrep

🤝 Contributing

Contributions are welcome! Please visit our Butterforge repository to:

• Report issues: https://justaguy.dev/drew/butterbash/issues
• Submit pull requests
• Join discussions

For major changes, please open an issue first to discuss your ideas.

License

GPL-2.0 - See LICENSE for details.

Support

Connect

• YouTube — tutorials and guides
• Butterforge — source code and projects
• The Butter Lab — Discourse forum
• The Churn — community chat (Fluxer)
• Wiki — documentation and guides
• Mastodon — @justaguylinux@fosstodon.org
• Butterbian — a Debian-based distro

---

Made with butter by JustAGuyLinux