# bash-completion-setup

**Repository Path**: Asheng008/bash-completion-setup

## Basic Information

- **Project Name**: bash-completion-setup
- **Description**: 一个用于自动设置Bash命令补全功能的开源项目，简化配置过程，提升终端使用体验。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-23
- **Last Updated**: 2026-06-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# bash-completion-setup — Bash 补全环境搭建工具集

> 涵盖 bash 可编程补全（Programmable Completion）的完整知识体系与实用工具箱：
> 从环境搭建、自定义补全脚本编写，到调试诊断，一站式解决方案。

---

## 快速索引

| 序号 | 文件 | 用途 | 优先级 |
|------|------|------|--------|
| ① | `1-setup-bash-completion.sh` | **一键安装** fzf/fd/bat/eza | ⭐ 最先执行 |
| ② | `2-fzf-config.bash` | **fzf 集成配置**（供 .bashrc 引用） | 路线 A |
| ③ | `3-bashrc-completion.bash` | **完整 .bashrc** 补全配置段 | 路线 B |
| — | **ble.sh + `.blerc`** | **极致增强**（语法高亮 + 实时建议） | 路线 C |
| ④ | `4-mytool.bash` | **入门示例**补全脚本 | 学习使用 |
| ⑤ | `5-deploy-cli.bash` | **进阶示例**补全脚本 | 学习使用 |
| ⑥ | `6-debug-completion.bash` | **调试工具箱** | 日常排错 |

> **三条路线三选一**：② fzf 轻量 / ③ 完整集成 / ble.sh 极致。详见第二步。

---

## 第一步：安装增强工具（① → `1-setup-bash-completion.sh`）

```bash
cd bash-completion-setup

# 方式一：安装全部推荐工具（fzf + fd + bat + eza）
./1-setup-bash-completion.sh

# 方式二：仅安装核心 fzf（其他可选，日后可补装）
./1-setup-bash-completion.sh --minimal

# 方式三：先预览要装什么，再决定
./1-setup-bash-completion.sh --dry-run
```

安装脚本会自动检测你的发行版（Debian/Ubuntu/Fedora/Arch），选择合适的包管理器进行安装。

**装了什么？**

| 工具 | 作用 |
|------|------|
| **fzf** | 模糊搜索历史(Ctrl+R)、文件(Ctrl+T)、目录(Alt+C)，`**<Tab>` 触发式补全 |
| **fd** | 替代 `find`，快 5~10 倍，自动遵守 `.gitignore` |
| **bat** | 带语法高亮的文件预览（配合 fzf 使用） |
| **eza** | 带图标的目录树预览（配合 fzf 使用） |

---

## 第二步：集成 fzf 到当前 shell（② → `2-fzf-config.bash`）

```bash
# 临时加载（仅当前 shell 生效）
source ~/bash-completion-setup/2-fzf-config.bash

# 永久生效：在 ~/.bashrc 末尾添加
echo 'source ~/bash-completion-setup/2-fzf-config.bash' >> ~/.bashrc
```

加载后立即获得的能力：

| 操作 | 快捷键 | 效果 |
|------|--------|------|
| 模糊搜索历史命令 | `Ctrl+R` | 输入关键词实时过滤 |
| 模糊搜索文件/目录 | `Ctrl+T` | 在当前目录搜索，带 bat 预览 |
| 快速 cd | `Alt+C` | 模糊搜索目录并跳转，带 eza 树状预览 |
| 触发式补全 | `vim **<Tab>` | 弹出 fzf 窗口选文件 |
| 杀死进程 | `kill -9 **<Tab>` | 模糊搜索进程（带进程信息预览） |

### 替代方案：使用完整配置段（③ → `3-bashrc-completion.bash`）

如果你想要一个更完整的 `.bashrc` 配置（包含 bash-completion + zoxide + fzf + Readline 增强），可以用这个文件替代上一步：

```bash
# 查看内容
less ~/bash-completion-setup/3-bashrc-completion.bash

# 集成到 .bashrc
cat ~/bash-completion-setup/3-bashrc-completion.bash >> ~/.bashrc
```

### 路线 C（极致）：ble.sh + fzf 集成

已安装 ble.sh 的用户，在 `~/.blerc` 中集成 fzf，而非在 `.bashrc` 中直接 `eval "$(fzf --bash)"`：

```bash
# ~/.blerc
ble-import -d integration/fzf-completion
ble-import -d integration/fzf-key-bindings
```

`.bashrc` 中只需加载 ble.sh，不再加载 `2-fzf-config.bash` 或 `3-bashrc-completion.bash`：

```bash
[ -f ~/.local/share/blesh/ble.sh ] && source ~/.local/share/blesh/ble.sh
```

> **注意**：三条路线三选一，不要混用。详见 `bash-completion-best-practices.md` 第 5 章。

---

## 第三步：加载补全脚本

安装脚本会自动放入 `~/.local/share/bash-completion/completions/` 目录。
**bash-completion >= 2.18 会自动按需加载**，无需手动 source。

如果你已经打开了新的终端，直接输入命令按 Tab 即可测试：

```bash
mytool <Tab>              # 显示子命令和选项
mytool create --<Tab>     # 显示 create 的选项
mytool create --format=<Tab>  # 显示格式列表 (json/yaml/table/text)

deploy-cli <Tab>                      # 显示子命令
deploy-cli deploy --env=<Tab>         # 显示环境列表
deploy-cli deploy --service=<Tab>     # 显示服务列表
deploy-cli deploy --version=<Tab>     # 显示版本列表
```

如果要在当前 shell 立即测试：

```bash
# 手动加载（当前 shell 生效）
source ~/bash-completion-setup/4-mytool.bash

# 再按 Tab 测试
mytool <Tab>
```

---

## 两个示例脚本的异同

| 对比维度 | ④ `4-mytool.bash` | ⑤ `5-deploy-cli.bash` |
|----------|-----------------|---------------------|
| 难度 | ⭐ 入门 | ⭐⭐⭐ 进阶 |
| 子命令层级 | 1 级（create/delete/list/get/help） | 4 级（deploy/rollback/status/logs/config） |
| `--flag=value` | ✅ 支持 | ✅ 支持 |
| 动态列表生成 | ❌ 静态词列表 | ✅ 函数动态生成（模拟 API） |
| 上下文感知 | ❌ 按前一词匹配 | ✅ 跨参数查找（如 --env 影响 --region） |
| 文件补全 | ✅ --config 补全 .conf | ✅ --file 补全 yaml/toml/json |
| 代码行数 | ~100 行 | ~186 行 |

---

## 调试工具（⑥ → `6-debug-completion.bash`）

当补全不生效或行为异常时，用这个工具箱诊断：

```bash
# 加载调试工具
source ~/bash-completion-setup/6-debug-completion.bash

# 常用命令
comp-help                  # 显示帮助
comp-list                  # 列出所有已注册的补全规则
comp-which mytool          # 查看 mytool 的补全规则详情
comp-test mytool --v       # 模拟测试补全输出
comp-test deploy-cli deploy --env=prod  # 测试 = 格式补全
comp-search mytool         # 查找 mytool 的补全文件位置
comp-rm mytool             # 临时移除 mytool 的补全规则
comp-load ~/.local/share/bash-completion/completions/mytool.bash  # 加载并验证补全脚本
```

### 常见问题速查

**Q: 补全不生效？**
```bash
# 1. 查看是否注册了规则
complete -p mytool

# 2. 查看补全函数是否定义
type _mytool

# 3. 用调试工具
source 6-debug-completion.bash
comp-which mytool
```

**Q: 想手动测试补全输出？**
```bash
source 6-debug-completion.bash
comp-test mytool --v
# 输出: --verbose --version
```

**Q: 补全文件放哪？**
```bash
# 用户级（自动加载，推荐）
~/.local/share/bash-completion/completions/<命令名>.bash

# 系统级
/usr/share/bash-completion/completions/<命令名>.bash
```

---

## 完整上手流程（从零开始）

### 路线 A/B：fzf 轻量 / 完整集成

```bash
# 1️⃣ 安装工具
cd ./
./1-setup-bash-completion.sh

# 2️⃣ 选择一条路线：
#    路线 A：仅 fzf
#    echo 'source ~/bash-completion-setup/2-fzf-config.bash' >> ~/.bashrc
#    路线 B：完整配置（含 zoxide + Readline 增强）
#    echo 'source ~/bash-completion-setup/3-bashrc-completion.bash' >> ~/.bashrc

# 3️⃣ 使配置生效
exec bash

# 4️⃣ 测试 fzf
Ctrl+R    # 搜索历史
Ctrl+T    # 搜索文件
```

### 路线 C：ble.sh 极致增强

```bash
# 1️⃣ 安装工具
cd ./
./1-setup-bash-completion.sh

# 2️⃣ 安装 ble.sh
sudo apt install gawk
git clone --recursive --depth 1 https://github.com/akinomyoga/ble.sh.git
cd ble.sh && make && make install
cd .. && rm -rf ble.sh

# 3️⃣ 配置 .bashrc
echo 'command -v zoxide &>/dev/null && eval "$(zoxide init bash)"' >> ~/.bashrc
echo '[ -f ~/.local/share/blesh/ble.sh ] && source ~/.local/share/blesh/ble.sh' >> ~/.bashrc

# 4️⃣ 创建 ~/.blerc，集成 fzf
cat > ~/.blerc << 'EOF'
source /usr/share/bash-completion/bash_completion
ble-import -d integration/fzf-completion
ble-import -d integration/fzf-key-bindings
EOF

# 5️⃣ 生效
exec bash
```

### 通用：测试补全 + 调试

```bash
# 测试补全
mytool <Tab>
mytool create --format=<Tab>

# 调试工具
source ~/bash-completion-setup/6-debug-completion.bash
comp-test mytool --v
```

---

## 待开发

| 方向 | 说明 |
|------|------|
| **补全脚本生成器** | 根据命令 `--help` 输出自动生成补全脚本骨架，降低编写门槛 |
| **在线补全脚本仓库** | 收集新工具（`gh`、`act`、`just`、`task` 等）缺失的补全脚本，一键安装 |
| **性能诊断工具** | `comp-bench` 测试补全响应时间，`comp-profile` 分析函数耗时 |
| **交互式安装向导** | 终端菜单引导，自动检测环境、推荐路线、配置 `.bashrc` 和 `.blerc` |
| **跨平台支持** | 扩展 macOS（brew）及其他 Linux 发行版的包管理器支持 |