🎯 Problem

Ever accidentally committed an API key? Hardcoded a password for testing? Left debug code in production?

Whiteout solves this by letting you maintain local-only code that never reaches your Git repository, while preserving safe alternatives in commits.

// What you see locally:
const apiKey = "process.env.API_KEY"; // @whiteout: "sk-proj-SUPER-SECRET-KEY-123"

// What gets committed:
const apiKey = "process.env.API_KEY";

✨ Features

• 🔐 Secure by Design - Secrets never touch Git history
• 🎨 Flexible Decorations - Multiple ways to mark sensitive code
• ⚡ Fast - Written in Rust for optimal performance
• 🔄 Seamless Integration - Works transparently with Git workflows
• 🌍 Language Agnostic - Works with any text file or programming language
• 💬 Multi-Comment Support - Works with //, #, -- comment styles
• 🛡️ Safe Defaults - Requires explicit marking to prevent accidents

📦 Installation

Prerequisites

• Git (version 2.0 or higher)

Install via Homebrew (macOS/Linux)

brew tap bytware/tap
brew install whiteout

Install via Cargo (All platforms)

cargo install whiteout-cli

Install from Source

# Clone the repository
git clone https://github.com/bytware/whiteout.git
cd whiteout

# Build and install
cargo build --release
sudo cp target/release/whiteout /usr/local/bin/

# Verify installation
whiteout --version

Install on Arch Linux (AUR)

# Using yay
yay -S whiteout-git

# Using paru
paru -S whiteout-git

🚀 Quick Start

1. Initialize in Your Project

cd your-project
whiteout init

This automatically:

• Creates .whiteout/ directory for local storage
• Configures Git filters in your repository
• Adds necessary .gitattributes entries

2. Mark Your Sensitive Code

Choose from multiple decoration styles that work with any comment format:

Inline Decoration

Works with any comment style (//, #, --):

// JavaScript
const apiKey = "sk-12345"; // @whiteout: "process.env.API_KEY"

# Python
api_key = "sk-12345"  # @whiteout: "os.environ['API_KEY']"

-- SQL
SELECT * FROM users WHERE key = 'sk-12345'; -- @whiteout: 'REDACTED'

Block Decoration

Hide entire code blocks between markers:

// @whiteout-start
const DEBUG = true;
const SECRET_ENDPOINT = "http://localhost:3000";
console.log("Debug mode active");
// @whiteout-end
const DEBUG = false;  // This line stays in commits

Simple Decoration

For markdown or documentation, hide content after a marker:

# Public Documentation

This content is committed.

\@whiteout
This content stays local only.
It won't appear in commits.

Back to public content.

Partial Replacement

For configuration values within strings:

const url = "https://[[localhost:3000||api.example.com]]/v1";
// Locally: uses localhost:3000
// Committed: uses api.example.com

3. Work Normally

# Edit your files with secrets
vim config.js

# Commit as usual - secrets are automatically removed
git add .
git commit -m "Add configuration"

# Your local files keep the secrets
cat config.js  # Still shows your secret values

🎭 Decoration Patterns

Inline Pattern

Syntax: <code> // @whiteout: <replacement>

Note: When documenting examples, escape the @ with backslash: \@whiteout

# Local version:
password = "getpass.getpass()"  # @whiteout: "admin123"

# Committed version:
password = "getpass.getpass()"

Block Pattern

Syntax: @whiteout-start ... @whiteout-end

# @whiteout-start
debug_mode: true
verbose_logging: true
test_endpoints:
  - localhost:8080
# @whiteout-end
production_mode: true  # This stays in commits

Simple Pattern

Syntax: @whiteout (hides everything until blank line)

Normal content here.

\@whiteout
Secret information.
More secrets.

Public content resumes.

Partial Pattern

Syntax: [[local||committed]]

[database]
host = "[[localhost||db.production.com]]"
port = [[5432||3306]]

📝 Documentation Escape Sequences

When writing documentation about Whiteout (like this README), use backslash to escape decorators:

# To show the literal text in docs:
\@whiteout           # Shows as @whiteout
\@whiteout-start     # Shows as @whiteout-start
\@whiteout-end       # Shows as @whiteout-end

# These are treated as actual decorators:
@whiteout           # Would hide content (without backslash)

🔧 Commands

Initialize Project

whiteout init [--path <dir>]

Manual Operations

# Apply clean filter (remove secrets)
whiteout clean < file.txt

# Apply smudge filter (restore secrets)
whiteout smudge < file.txt

🔄 How It Works

Whiteout uses Git's clean/smudge filter mechanism:

1. Clean Filter (Working → Repository): Removes decorated local values before commit
2. Smudge Filter (Repository → Working): Restores local values after checkout

graph LR
    A[Working Directory<br/>with secrets] -->|git add<br/>clean filter| B[Staging Area<br/>secrets removed]
    B -->|git commit| C[Repository<br/>safe version]
    C -->|git checkout<br/>smudge filter| A

Local values are stored in .whiteout/local.toml (gitignored) and restored automatically.

🆚 Whiteout vs .env Files

Both Whiteout and .env files solve secret management, but with different approaches:

Key Differences

Whiteout is Great For

• Inline secrets - See actual values where they're used
• Debug code - Hide entire blocks that shouldn't reach production
• Mixed visibility - Public and private code in the same file

.env Files are Great For

• Production config - Standard for deployment platforms
• Team workflows - Everyone knows how they work
• Docker/CI - Built-in support everywhere

They Work Well Together

Use each tool for what it does best:

// Production config from .env
const dbHost = process.env.DB_HOST;

// Development secrets inline with Whiteout
const apiKey = "process.env.API_KEY"; // @whiteout: "sk-dev-12345"

// Debug code that stays local
// @whiteout-start
console.log("Debug mode: connecting to local services");
const DEBUG = true;
// @whiteout-end

🔒 Security Considerations

• Never commit .whiteout/ directory (ensure it's in .gitignore)
• Local values are stored in .whiteout/local.toml
• Backup your local values separately
• Use environment variables for production secrets
• Review commits before pushing to ensure secrets are removed
• Test filters work correctly before committing sensitive data

🧪 Testing

# Run all tests
cargo test

# Run specific test
cargo test test_inline_parser

# Run with output
cargo test -- --nocapture

# Run integration tests
./tests/git_integration_test.sh

📋 Known Limitations / TODO

• Smudge operation after marker removal: When @whiteout markers are removed during the clean operation, the smudge filter cannot currently restore the hidden content when checking out files. This is a planned feature for a future release.

🤝 Contributing

Contributions are welcome!

Development

# Build
cargo build

# Test
cargo test

# Format code
cargo fmt

# Lint
cargo clippy

📄 License

MIT License - see LICENSE for details.

📚 Resources

• Git Attributes Documentation
• Git Filters Explained