Repository Hygiene Audit

Essential Files Checklist

.gitignore Essentials

Minimum patterns for any repo:

# Secrets
.env
.env.local
.env.*.local

# OS
.DS_Store
Thumbs.db
desktop.ini

# Editors
.vscode/
.idea/
*.swp
*.swo
*~

# Logs
*.log
logs/

# Dependencies (language-specific)
node_modules/
__pycache__/
*.pyc
.venv/
venv/
target/
vendor/

# Build artifacts
dist/
build/
out/
*.egg-info/

# Coverage
coverage/
.coverage
htmlcov/

Language additions:

• Node: node_modules/, dist/, .next/, .turbo/
• Python: pycache/, *.pyc, .venv/, venv/, .pytestcache/, .mypycache/
• Rust: target/, Cargo.lock (for libs, commit for bins)
• Go: vendor/, bin/
• Terraform: .terraform/, .tfstate, *.tfvars (if contains secrets)
• Java: target/, .gradle/, *.class

README Essentials

Minimum sections:

# Project Name

One-line tagline.

## Why
What problem does this solve?

## Install
Exact commands to install.

## Quick Start
Minimal working example.

## Usage
Common use cases with code examples.

## License
License name with link to LICENSE file.

Nice to have:

• Badges (build status, version, license)
• Screenshots/GIFs for visual tools
• Link to docs site
• Contributing section (even if just linking CONTRIBUTING.md)
• Acknowledgments / credits

.env.example Pattern

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/dbname

# Auth
JWT_SECRET=change-me-to-a-long-random-string
OAUTH_CLIENT_ID=your-oauth-client-id
OAUTH_CLIENT_SECRET=your-oauth-client-secret

# External APIs
OPENAI_API_KEY=sk-...
AWS_REGION=us-east-1

# Feature flags
ENABLE_BETA_FEATURES=false

Rules:

• Every variable the app reads at runtime
• Placeholder values that look like the real thing (so users know the format)
• Comments grouping related vars
• Never real credentials

Secret Scanning

Before publishing a repo publicly, scan for leaked secrets:

# Check git history for common patterns
git log -p | grep -iE 'api[_-]?key|secret|password|token|bearer' | grep -v example

# Dedicated tools
gitleaks detect --source=. --verbose
trufflehog git file://. --only-verified

# GitHub's own scanner runs automatically on public repos

If secrets are found in history:

1. Rotate them immediately
2. Use git filter-repo or BFG to remove from history
3. Force-push cleaned history
4. Enable GitHub secret scanning for the repo going forward

LICENSE Choice

Generate: https://choosealicense.com

Config File Hygiene

• Commit: package.json, requirements.txt, Dockerfile, tsconfig.json
• Commit with placeholders: .env.example, config.example.yml
• Do NOT commit: .env, config.yml (with real values), node_modules/, build artifacts
• Lock files (package-lock.json, yarn.lock, Cargo.lock, poetry.lock): commit for apps, skip for libs

Auditing an Existing Repo

1. Check for .gitignore -- does it cover your stack?
2. Check for README -- is it accurate and useful?
3. Check for LICENSE -- is there one?
4. Check for .env.example -- if app uses env vars
5. Scan for committed secrets (gitleaks)
6. Check for outdated dependencies
7. Check CI status -- is it green?
8. Check stale branches -- prune or merge
9. Check for TODO/FIXME density -- tech debt signal
10. Check commit message quality -- conventional commits?

Anti-Patterns