Skip to content

Quick Start Guide

Jump to bottom
Mikhail Deynekin edited this page Apr 10, 2026 · 3 revisions

🚀 Get Running in 5 Minutes

This guide covers the essentials to start using Clean BOM Senior right now.

Prerequisites

  • Linux, macOS, or WSL (Windows Subsystem for Linux)
  • Bash shell (v4.0 or newer)
  • Basic command-line knowledge
  • Read/write permissions on target files

Windows users: Use WSL or Git Bash for native support.

⚡ Step 1: Install Clean BOM Senior

Option A: Install via npm

Use the published npm package to install the global bom command:

npm install -g clean-bom-senior
bom --help

This is the fastest option if you already use Node.js and npm on your machine.

Option B: Download from GitHub

Get the latest version from the GitHub repository:

# Clone the repository
git clone https://github.com/paulmann/Clean_BOM_Senior.git
cd Clean_BOM_Senior

# Or download just the script
curl -O https://raw.githubusercontent.com/paulmann/Clean_BOM_Senior/main/clean-bom-senior.sh

# Make it executable
chmod +x clean-bom-senior.sh

🔒 Step 2: Check Your Files

Before making changes, preview what will be done:

# Dry-run: See what will change without modifying anything
./clean-bom-senior.sh --dry-run /path/to/your/files

If you installed via npm, you can use the global command instead:

bom --dry-run /path/to/your/files

🔒 Step 2: Check Your Files

Before making changes, preview what will be done:

# Dry-run: See what will change without modifying anything
./clean-bom-senior.sh --dry-run /path/to/your/files

Output example:

[DRY-RUN] Scanning: /path/to/your/files
[BOM DETECTED] file1.txt (UTF-8 BOM)
[BOM DETECTED] file2.php (UTF-8 BOM)
[NO CHANGES] file3.md
Total files processed: 3
Files to be cleaned: 2

🙻 Step 3: Run the Cleaner

Once you're confident about the changes:

# Clean BOM from all files
./clean-bom-senior.sh /path/to/your/files

For a single directory with all subdirectories:

# This is the most common use case
./clean-bom-senior.sh ~/my-project

💾 Step 4: Verify Results

Check what was cleaned:

# Show detailed report
./clean-bom-senior.sh --verbose /path/to/your/files

Output includes:

  • Files processed
  • BOM types detected
  • Encoding changes made
  • Files skipped and why

💫 Common Examples

Example 1: Clean a Single Directory

# Clean all files in current directory
./clean-bom-senior.sh .

# Clean a project directory
./clean-bom-senior.sh ~/my-website

# Clean a nested project
./clean-bom-senior.sh /var/www/html

Example 2: Create Backups Before Cleaning

Keep original files with .bak extension:

./clean-bom-senior.sh --backup /path/to/files

This creates:

original.txt
original.txt.bak  ← backup copy

Example 3: Clean Only Specific File Type

Process only PHP files:

./clean-bom-senior.sh --file-type php /path/to/project

Example 4: Exclude Certain Directories

./clean-bom-senior.sh --exclude node_modules,vendor /path/to/project

Example 5: Process Only Text Files

./clean-bom-senior.sh --file-type text /path/to/project

🔍 What Gets Cleaned?

The script automatically detects and processes:

  • Code Files: PHP, Python, JavaScript, Java, C/C++, Go, Rust
  • Markup: HTML, XML, JSON, YAML, TOML
  • Data: CSV, TSV, SQL, SRT
  • Config: .htaccess, .conf, .ini, .env
  • Styles: CSS, SCSS, LESS
  • Templates: Blade, Twig, Mustache
  • Text: Plain text, Markdown, RST

For complete list, see File Types and Detection.

✅ Verification Checklist

Before you start, make sure:

  • You have read/write permissions on the directory
  • You have a backup (optional but recommended)
  • You tested with --dry-run first
  • You understand which files will be affected

After cleaning:

  • Check files open correctly in your editor
  • Verify no encoding issues in version control
  • Test your application/website
  • Confirm Git no longer flags encoding problems

🆘 Need Help?

What if nothing happens?
→ Try with --verbose flag to see details

Worried about breaking something?
→ Use --backup to keep originals, or --dry-run first

Want to undo changes?
→ Restore from Git: git checkout -- . or restore .bak files

Specific file type causing issues?
→ Check File Types and Detection

Still stuck?
→ Visit Troubleshooting Guide or FAQ

🔧 Available Options

Option Purpose Example
--dry-run Preview changes without modifying --dry-run /path
--backup Create .bak backup files --backup /path
--verbose Show detailed report --verbose /path
--file-type Process only specific type --file-type php /path
--exclude Skip directories --exclude vendor,node_modules /path
--fix-gitattributes Update .gitattributes --fix-gitattributes

For complete reference: Command-Line Reference

🚀 Next Steps

Want to understand more?
→ Read Understanding BOM and CRLF

Need all command details?
→ Check Command-Line Reference

Integrating with CI/CD?
→ See CI/CD Integration Guide

Troubleshooting an issue?
→ Visit Troubleshooting Guide

💡 Pro Tips

  1. Always dry-run first - Use --dry-run before making changes
  2. Use backups for safety - Add --backup when first learning
  3. Combine with version control - Work in a Git branch for easy rollback
  4. Schedule for regular use - Add to CI/CD pipeline for automation
  5. Monitor output - Use --verbose to see exactly what changed

You're all set! Start with step 1 and you'll be cleaning BOM artifacts in minutes.

Clone this wiki locally