# Bash Style

当用户操作 .sh、Dockerfile、Makefile、.yml、.yaml 文件，或在 Markdown 中编写 bash 代码块时触发。提供 Bash 编写规范。

- Repository: https://github.com/doccker/cc-use-exp (1063 stars)
- Category: Engineering
- License: see repository
- Last updated: 2026-08-26
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add doccker/cc-use-exp --skill bash-style -g -a claude-code -y`
Codex: `npx skills add doccker/cc-use-exp --skill bash-style -g -a codex -y`
Cursor: `npx skills add doccker/cc-use-exp --skill bash-style -g -a cursor -y`
Gemini CLI: `npx skills add doccker/cc-use-exp --skill bash-style -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add doccker/cc-use-exp`

## Description

当用户操作 .sh、Dockerfile、Makefile、.yml、.yaml 文件，或在 Markdown 中编写 bash 代码块时触发。提供 Bash 编写规范。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Bash 编写规范

版本：v1.0
更新：2026-01

---

## 1. 注释规范

### 禁止行尾注释

- ❌ **禁止行尾注释**（如 `command # 注释`）
- ✅ 注释应独占一行，放在代码上方

**适用范围**：
- Shell 脚本文件（.sh）
- Markdown 文档中的 bash 代码块
- Dockerfile、Makefile 中的 shell 命令

```bash
# ❌ 错误：行尾注释
curl -X POST https://api.example.com/data # 发送请求
docker run -d nginx # 启动容器
cp -r src/ dist/ # 复制文件

# ✅ 正确：注释独占一行
# 发送请求
curl -X POST https://api.example.com/data

# 启动容器
docker run -d nginx

# 复制文件
cp -r src/ dist/
```

**原因**：
- 复制粘贴时容易带上注释导致命令出错
- 长命令 + 注释 = 超长行，可读性差
- Heredoc 块内 `#` 不是注释而是内容

---

## 2. 文件写入方式

### 推荐方式：tee 命令

```bash
# ✅ 推荐：简洁、无嵌套引号
sudo tee /etc/fail2ban/jail.d/docker-nginx.local > /dev/null << 'EOF'
[docker-nginx]
enabled = true
filter = docker-nginx
logpath = /var/log/nginx/access.log
maxretry = 5
EOF
```

### 追加内容

```bash
# ✅ 追加到文件
sudo tee -a /etc/hosts > /dev/null << 'EOF'
192.168.1.100 myserver
EOF

# ✅ 单行追加
echo '192.168.1.100 myserver' | sudo tee -a /etc/hosts
```

### 避免的写法

```bash
# ❌ 避免：嵌套引号复杂，易出错
sudo bash -c 'cat > /etc/xxx << EOF
content
EOF'

# ❌ 避免：需要转义内容中的特殊字符
sudo sh -c "echo 'line1\nline2' > /etc/xxx"
```

### 方式对比

| 方式 | 优点 | 缺点 | 推荐场景 |
|------|------|------|---------|
| `sudo tee` | 简洁、无嵌套 | 需 `> /dev/null` 抑制输出 | **首选** |
| `sudo bash -c 'cat >'` | 无需 tee | 嵌套引号复杂 | 不推荐 |
| 临时文件 + mv | 可先验证 | 步骤多 | 复杂配置 |

---

## 3. Heredoc 引号规则

### 禁止变量展开（推荐默认）

```bash
# ✅ 'EOF' 带引号：内容原样输出，不解析变量
sudo tee /etc/xxx > /dev/null << 'EOF'
$HOME 不会被展开
$(command) 不会被执行
EOF
```

### 需要变量展开

```bash
# EOF 不带引号：变量会被展开
sudo tee /etc/xxx > /dev/null << EOF
当前用户: $USER
当前目录: $(pwd)
EOF
```

### 选择原则

| 场景 | 用法 | 原因 |
|------|------|------|
| 配置文件 | `<< 'EOF'` | 避免意外展开 |
| 模板生成 | `<< EOF` | 需要插入变量 |
| 不确定时 | `<< 'EOF'` | 更安全 |

---

## 4. 权限与路径

### 需要 root 权限

```bash
# ✅ 正确：tee 配合 sudo
echo 'content' | sudo tee /etc/xxx

# ❌ 错误：重定向在 sudo 之外，权限不足
sudo echo 'content' > /etc/xxx
```

### 路径带空格

```bash
# ✅ 正确：双引号包裹路径
sudo tee "/etc/my config/file.conf" > /dev/null << 'EOF'
content
EOF
```

---

## 5. 脚本规范

### 文件头

The rest: https://github.com/doccker/cc-use-exp/blob/HEAD/.antigravity/skills/bash-style/SKILL.md