🚀 Getting Started

5-Minute Setup

This guide will get Guardy protecting your code in just 5 minutes. We'll install Guardy, set up hooks, and make your first protected commit.

Step 1: Install Guardy (30 seconds)

Choose your preferred method:

# Download and install in one command
curl -sSf https://guardy.run | sh

# Verify installation
guardy --version

# Install via mise package manager
mise use -g cargo:guardy

# Verify installation
guardy --version

# Install via Rust's cargo
cargo install guardy

# Verify installation
guardy --version

Step 2: Initialize Your Project (30 seconds)

Navigate to your Git repository and install hooks:

# Go to your project
cd your-project

# Install Guardy hooks
guardy hooks install

This command:

✅ Creates .guardy.yaml configuration
✅ Installs git hooks in .git/hooks/
✅ Enables secret scanning by default
✅ Sets up conventional commits validation

Step 3: Your First Protected Commit (1 minute)

Let's test that Guardy is working:

Test Secret Detection

Try to commit a file with a secret:

# Create a test file with a fake API key
echo "API_KEY=sk_live_abcd1234efgh5678ijkl9012mnop3456" > test.txt

# Try to commit it
git add test.txt
git commit -m "test: add config"

Guardy will block this commit:

🛡️ guardy v0.3.0 hook: pre-commit
┃  scan_secrets (started) ❯
❌ Secret detected in test.txt
   Type: Stripe API Key
   Line: 1
   Confidence: High (0.95)
✗ Pre-commit hook failed: secrets detected

Make a Clean Commit

Remove the secret and try again:

# Remove the secret
echo "# Safe configuration file" > test.txt

# Commit successfully
git add test.txt
git commit -m "test: add safe config"

Success! Guardy checked and approved your commit.

Step 4: Customize Your Setup (2 minutes)

Edit .guardy.yaml to fit your workflow:

Example: JavaScript/TypeScript Project

# .guardy.yaml
hooks:
  pre-commit:
    parallel: true  # Run checks in parallel
    builtin: ["scan_secrets"]
    custom:
      - command: "npm run lint:fix"
        description: "Fix ESLint issues"
        glob: ["*.{js,ts,jsx,tsx}"]
        stage_fixed: true  # Auto-stage fixed files

      - command: "npm run format"
        description: "Format with Prettier"
        glob: ["*.{js,ts,jsx,tsx,json,md}"]
        stage_fixed: true

  commit-msg:
    builtin: ["conventional_commits"]

  pre-push:
    custom:
      - command: "npm test"
        description: "Run tests before push"
        fail_on_error: true

scanner:
  patterns:
    - name: "NPM Token"
      regex: 'npm_[A-Za-z0-9]{36}'
      confidence: 0.9

Example: Rust Project

# .guardy.yaml
hooks:
  pre-commit:
    parallel: true
    builtin: ["scan_secrets"]
    custom:
      - command: "cargo fmt -- --check"
        description: "Check Rust formatting"
        glob: ["*.rs"]

      - command: "cargo clippy -- -D warnings"
        description: "Run Clippy lints"
        glob: ["*.rs"]

  pre-push:
    custom:
      - command: "cargo test"
        description: "Run all tests"
        fail_on_error: true

Example: Python Project

# .guardy.yaml
hooks:
  pre-commit:
    parallel: true
    builtin: ["scan_secrets"]
    custom:
      - command: "black {staged_files} --check"
        description: "Check Python formatting"
        glob: ["*.py"]

      - command: "ruff check {staged_files}"
        description: "Run Ruff linter"
        glob: ["*.py"]

      - command: "mypy {staged_files}"
        description: "Type check with mypy"
        glob: ["*.py"]

  pre-push:
    custom:
      - command: "pytest"
        description: "Run pytest suite"

Step 5: Verify Everything Works (1 minute)

Run these commands to ensure your setup is complete:

# Check Guardy status
guardy status

# Manually test hooks
guardy hooks run pre-commit
guardy hooks run commit-msg --message "feat: test message"

# View current configuration
guardy config dump

Expected output:

✅ Guardy Status Report
────────────────────────
Installation: ✓ Guardy v0.3.0 installed
Configuration: ✓ Found .guardy.yaml
Hooks: ✓ 3 hooks installed (pre-commit, commit-msg, pre-push)
Scanner: ✓ 100+ patterns loaded

Common Patterns

Skip Hooks Temporarily

When you need to bypass hooks (use sparingly!):

# Skip all hooks
GUARDY_SKIP=1 git commit -m "emergency: fix production"

# Skip specific hook
GUARDY_SKIP_PRE_COMMIT=1 git commit -m "wip: debugging"

Run Hooks Manually

Test hooks without committing:

# Test pre-commit on staged files
guardy hooks run pre-commit

# Test on specific files
guardy hooks run pre-commit --files src/main.rs,src/lib.rs

# Test commit message validation
guardy hooks run commit-msg --message "feat: new feature"

Scan Specific Files

Run secret scanning independently:

# Scan current directory
guardy scan

# Scan specific files
guardy scan src/ config/

# Scan with detailed output
guardy scan --verbose

Next Steps

Now that Guardy is protecting your code:

Essential Reads

Configuration Guide - Deep dive into all configuration options
Git Hooks - Master hook customization
Secret Scanning - Configure detection patterns

Advanced Topics

File Synchronization - Share configs across repositories
CI/CD Integration - Use in pipelines
Custom Patterns - Create your own detectors

Get Help

Run guardy --help for command help
Check Troubleshooting for common issues
Report bugs on GitLab

Tips for Success

🎯 Start Simple

Begin with just secret scanning, then gradually add more checks.

⚡ Use Parallel Execution

Set parallel: true in hooks for faster execution.

📝 Commit Message Standards

Use conventional commits for better changelog generation.

🔍 Test Before Committing

Run guardy hooks run pre-commit to test without committing.

🚀 Optimize for Speed

Use glob patterns to only check relevant files.

🔧 Customize Patterns

Add project-specific secret patterns for better protection.

Ready to secure more projects? Check our installation guide for system-wide setup options.

🚀 Getting Started

On this page