securegit 0.8.5

# SecureGit Usage Tips and Best Practices

## Command Aliases

If `securegit` feels too long to type, create an alias:

### Bash/Zsh

Add to `~/.bashrc` or `~/.zshrc`:

```bash
# Short alias
alias sgit='securegit'

# Even shorter
alias sg='securegit'

# Common workflows
alias sgacquire='securegit acquire'
alias sgscan='securegit scan'
alias sgplugin='securegit plugin'
```

**Usage:**
```bash
# Instead of
securegit acquire https://github.com/user/repo /tmp/repo

# Use
sgit acquire https://github.com/user/repo /tmp/repo

# Or
sg acquire https://github.com/user/repo /tmp/repo
```

### Fish Shell

Add to `~/.config/fish/config.fish`:

```fish
alias sgit='securegit'
alias sg='securegit'
```

### Windows PowerShell

Add to PowerShell profile:

```powershell
Set-Alias -Name sgit -Value securegit
Set-Alias -Name sg -Value securegit
```

### Git-Style Alias

For a git-like workflow:

```bash
alias git-secure='securegit acquire'
```

**Usage:**
```bash
# Clone-like syntax
git-secure https://github.com/user/repo /tmp/repo
```

## Workflow Integration

### Replace `git clone`

**Traditional workflow:**
```bash
git clone https://github.com/user/untrusted-repo
cd untrusted-repo
```

**SecureGit workflow:**
```bash
sgit acquire https://github.com/user/untrusted-repo untrusted-repo
cd untrusted-repo
```

### Pre-Commit Hook

Add to `.git/hooks/pre-commit`:

```bash
#!/bin/bash
# Scan staged files before commit

sgit scan --staged --fail-on high || {
    echo "Security scan failed. Commit blocked."
    exit 1
}
```

### Development Alias Collection

Create a `~/.securegit_aliases` file:

```bash
# Quick scan current directory
alias scan-here='sgit scan .'

# Scan with specific plugins only
alias scan-secrets='sgit scan . --plugins secrets,gitleaks'

# Scan and ignore common false positives
alias scan-clean='sgit scan . --skip-paths "**/node_modules/**,**/vendor/**"'

# Quick plugin check
alias plugin-status='sgit plugin list && sgit plugin check-updates'

# Acquire to specific safe directory
alias safe-clone='sgit acquire'

# Scan PR branch
alias scan-pr='git diff main --name-only | xargs sgit scan'
```

Source in your shell:
```bash
echo "source ~/.securegit_aliases" >> ~/.bashrc
```

## Beta Tester Recommendations

### Suggested Aliases for Testing

**Minimal setup:**
```bash
alias sgit='securegit'
```

**Comfortable setup:**
```bash
alias sgit='securegit'
alias sgacq='securegit acquire'
alias sgscan='securegit scan'
alias sgplug='securegit plugin'
```

**Power user setup:**
```bash
# Main command
alias sgit='securegit'

# Subcommands
alias sgacq='securegit acquire'
alias sgscan='securegit scan'
alias sgplug='securegit plugin'

# Common workflows
alias safe-clone='securegit acquire'
alias scan-here='securegit scan .'
alias scan-deep='securegit scan . --include-git'
alias plugin-update='securegit plugin update --all'

# Integration with git
alias git-safe='securegit acquire'
alias git-scan='securegit scan'
```

### Feedback Request

During beta testing, please share:
- What alias(es) you use
- Whether the default name is too long
- If we should provide default aliases
- Suggested alternative command names

## Alternative Command Names

If testing reveals strong preference, we could consider:

### Shorter Options
- `sgit` - Secure Git (4 chars)
- `safegit` - Safe Git (7 chars)
- `secgit` - Secure Git (6 chars)

### Alternative Concepts
- `trustless` - Emphasizes zero-trust
- `verigit` - Verification + Git
- `cleangit` - Clean/sanitized Git

### Feedback Question
**Which feels most natural to you?**
- [ ] `securegit` (current)
- [ ] `sgit`
- [ ] `safegit`
- [ ] `secgit`
- [ ] Other: ___________

## Binary Naming Convention

Current recommendation: Keep `securegit` as the official binary name, let users alias as preferred.

**Rationale:**
- Clear, descriptive name for discovery
- No ambiguity about purpose
- Users can easily alias to preference
- Documentation uses consistent name

**Compromise:**
- Ship with example aliases in README
- Include shell completion for common aliases
- Document aliasing in quick start guide

## Tab Completion

Enable tab completion for the alias:

### Bash

```bash
# Add to ~/.bashrc
complete -F _securegit sgit
complete -F _securegit sg
```

### Zsh

```zsh
# Add to ~/.zshrc
compdef sgit=securegit
compdef sg=securegit
```

## Environment Variables

Customize behavior with environment variables:

```bash
# Use custom config directory
export SECUREGIT_CONFIG_DIR=~/.config/my-securegit

# Default severity threshold
export SECUREGIT_FAIL_ON=high

# Skip certain paths by default
export SECUREGIT_SKIP_PATHS="**/node_modules/**:**/vendor/**"

# Enable verbose output
export SECUREGIT_VERBOSE=1
```

Add to aliases:
```bash
alias sgit='SECUREGIT_VERBOSE=1 securegit'
```

## Quick Reference Card

Print this and keep near your desk during testing:

```
SecureGit Quick Reference

ACQUISITION:
  sgit acquire <url> <path>     Clone safely
  sgit acquire <url> .          Acquire to current dir

SCANNING:
  sgit scan <path>               Basic scan
  sgit scan . --fail-on high     Fail on high severity
  sgit scan . --include-git      Scan .git directory

PLUGINS:
  sgit plugin list               Show installed
  sgit plugin install <name>     Install plugin
  sgit plugin check-updates      Check for updates
  sgit plugin update --all       Update all plugins

HELP:
  sgit --help                    Main help
  sgit <command> --help          Command help
  sgit --version                 Show version

CONFIG:
  ~/.config/securegit/config.toml
  ~/.config/securegit/plugins/
```

## Productivity Tips

### 1. Scan Before Reviewing

```bash
# Acquire and scan in one line
sgit acquire https://github.com/user/repo /tmp/repo && sgit scan /tmp/repo
```

### 2. Background Scanning

```bash
# Scan in background, review results later
sgit scan large-repo > scan-results.txt 2>&1 &
```

### 3. Filter by Severity

```bash
# Only show critical and high
sgit scan . --min-severity high
```

### 4. JSON Output for Tooling

```bash
# Get JSON output for parsing
sgit scan . --format json > results.json

# Use with jq
sgit scan . --format json | jq '.findings[] | select(.severity == "critical")'
```

### 5. Incremental Scanning

```bash
# Scan only changed files (git-aware)
git diff --name-only main | xargs sgit scan

# Scan staged files
git diff --cached --name-only | xargs sgit scan
```

## Beta Test Specific Tips

### Daily Testing Routine

**Morning:**
```bash
sgit plugin check-updates
```

**Before using new dependency:**
```bash
sgit acquire <repo-url> /tmp/check-repo
sgit scan /tmp/check-repo
# Review results, then use if safe
```

**Before committing:**
```bash
sgit scan --staged
```

**End of day:**
```bash
# Quick feedback note
echo "$(date): Tested <feature>, found <issue>" >> ~/securegit-notes.txt
```

### Feedback Collection Helpers

Create feedback alias:
```bash
alias sgfeedback='echo "Feature: | Like: | Dislike: | Bug: " >> ~/securegit-feedback.txt && vim ~/securegit-feedback.txt'
```

### Testing Checklist Alias

```bash
alias sgtest='cat << EOF
SecureGit Testing Checklist
[ ] Install/update worked
[ ] Acquired a repository
[ ] Ran a scan
[ ] Installed a plugin
[ ] Found a bug? Report it
[ ] Quick feedback: sgfeedback
EOF'
```

## Share Your Setup!

During beta testing, please share:
1. Your alias configuration
2. Any custom scripts or integrations
3. Workflow improvements you discovered
4. What made you more productive

This helps us:
- Provide better default configuration
- Create better documentation
- Understand real usage patterns
- Build features users actually want

## Conclusion

The command name `securegit` is intentionally descriptive, but we recognize it can feel verbose for daily use. Setting up aliases takes 30 seconds and makes the tool feel much more natural.

**Recommendation for beta testers:** Start with `alias sgit='securegit'` and see how it feels. Share what works for you!