echo-comment

A bidirectional bash interpreter that converts between comments and echo statements, making your shell scripts cleaner and more maintainable.

The Problem

Ever written a shell script like this?

#!/usr/bin/env bash
set -euo pipefail

echo "🧹 Cleaning up any existing .so files..."
find python/ -name "*.so" -delete || true

echo "📋 Running pre-commit checks..."
pre-commit run --all-files

echo "🔨 Building fresh release version..."
maturin develop --release

echo "📦 Downloading wheel artifacts..."
gh run download "${latest_run_id}" -p wheel*

The actual business logic is completely obscured by echo statements!

The Solution

Write your scripts with clean comments instead:

#!/usr/bin/env echo-comment
set -euo pipefail

# 🧹 Cleaning up any existing .so files...
find python/ -name "*.so" -delete || true

# 📋 Running pre-commit checks...
pre-commit run --all-files

# 🔨 Building fresh release version...
maturin develop --release

# 📦 Downloading wheel artifacts...
gh run download "${latest_run_id}" -p wheel*

At runtime, echo-comment automatically converts comments to echo statements, so you get the verbose output without cluttering your source code.

To write a comment that doesn't get echoed, simply start the line with 2: ## ...

Demo

Here is our script hello.sh with 3 steps

• Python: We use Python to print "🐍 Hiss" and "🐱 Meow" and grep the snake emoji
• Pause: Then we do a no-op using the bash : operator
• Echo Lastly we echo "Goodbye"

# 1) Run some Python
python -c 'print("\N{SNAKE} Hiss\n\N{CAT FACE} Meow")' | grep 🐍

# 2) Pause for effect...
:

# 3) Complete
echo "Goodbye"

bash

Run normally, you get Hiss and Goodbye:

bash hello.sh 

⇣

🐍 Hiss
Goodbye

echo-comment

'Echo the comments': a running commentary on all 3 steps:

echo-comment hello.sh 

⇣

1) Run some Python
🐍 Hiss
2) Pause for effect...
3) Complete
Goodbye

comment-echo

'Comment out the echoes': Hiss, no Goodbye:

comment-echo hello.sh 

⇣

🐍 Hiss

Features

• Bidirectional: echo-comment (comments → echoes) and comment-echo (echoes → comments)
• Perfect for Justfiles: Clean recipes that become verbose at runtime
• Preserves formatting: Maintains indentation and structure
• Opt out: Use ## for silent comments that won't be echoed, #\# to echo text starting with #
• No dependencies: Ships as a single binary
• Cross-platform: Works on Linux, macOS, and Windows

Installation

Option 1: Install from crates.io

cargo install comment-echo

Option 2: Install with cargo-binstall

cargo binstall comment-echo

Option 3: Build from source

git clone https://github.com/lmmx/echo-comment
cd echo-comment
cargo build --release

Both echo-comment and comment-echo binaries will be installed.

Usage

With Justfiles (Recommended)

Create clean, readable recipes:

# justfile
build-and-publish:
    #!/usr/bin/env echo-comment
    set -euo pipefail
    
    # 🧹 Cleaning up build artifacts...
    find . -name "*.so" -delete || true
    
    # 📋 Running tests...
    cargo test
    
    # 🚀 Publishing...
    cargo publish

When you run just build-and-publish, you'll see:

🧹 Cleaning up build artifacts...
📋 Running tests...
🚀 Publishing...

Ship Binary with Your Project

For maximum portability, ship the binary in your repo:

# Build and copy to your project
cargo build --release
cp target/release/comment-echo bin/comment-echo
cp target/release/echo-comment bin/echo-comment
chmod +x bin/comment-echo bin/echo-comment

Then use relative paths in your justfile:

build:
    #!/usr/bin/env bin/comment-echo
    # Your clean script here...

Standalone Script Usage

# Convert comments to echoes and run
echo-comment script.sh

# Convert echoes to comments and run  
comment-echo verbose-script.sh

# Pass arguments to the script
echo-comment deploy.sh --env=production

Mode

The tool runs in either mode based on the binary name:

• echo-comment: Converts # comments → echo "comments"
• comment-echo: Converts echo "text" → # text

Examples

Converting Comments to Echoes

Input (script.sh):

#!/usr/bin/env bash
set -euo pipefail

# Starting deployment process
kubectl apply -f deployment.yaml

# Waiting for rollout
kubectl rollout status deployment/app

# Deployment complete!
echo "App is now live"

Running with echo-comment script.sh:

#!/usr/bin/env bash
set -euo pipefail

echo "Starting deployment process"
kubectl apply -f deployment.yaml

echo "Waiting for rollout" 
kubectl rollout status deployment/app

echo "Deployment complete!"
echo "App is now live"

Converting Echoes to Comments

Input (verbose.sh):

#!/usr/bin/env bash
echo "Backing up database"
pg_dump mydb > backup.sql
echo "Database backed up successfully"

Running with comment-echo verbose.sh:

#!/usr/bin/env bash
# Backing up database
pg_dump mydb > backup.sql  
# Database backed up successfully

Why This Approach?

1. Low line noise: Unlike bash -v or set -x, you just see the comment text
2. Readability: Foreground your actual logic with syntax highlighting
3. Better Diffs: Code changes are separate from message changes
4. Maintainability: Makes it trivial to document code

Contributing

Contributions welcome! Please feel free to submit a Pull Request.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.