Skip to content

USAGE.md

Latest commit

 

History

History
259 lines (173 loc) · 4.89 KB

USAGE.md

File metadata and controls

259 lines (173 loc) · 4.89 KB
Raw

GitWizard Usage Guide

Quick Start

# Instead of:
git commit

# Use:
gitwiz

Features Walkthrough

1. Commit Subject

The wizard prompts you for a commit subject line:

  • Must be non-empty
  • Recommended: 50 characters or less
  • Maximum: 72 characters
  • Should be imperative mood ("Add feature" not "Added feature")

Example:

✓ "Fix user authentication bug"
✓ "Add dark mode support"
✗ "fixed stuff" (too vague)
✗ "This commit adds a new feature that allows users to..." (too long)

2. Commit Body (Optional)

Detailed explanation of your changes:

  • Press ESC when done editing
  • Can be multi-line
  • Explain the "why", not just the "what"

Example:

The previous authentication flow had a race condition
when multiple requests arrived simultaneously. This fix
adds mutex locking around the session store.

3. Co-Authors

GitWizard automatically scrapes contributors from the last 3 months:

  • Excludes your own email
  • Multi-select with space bar
  • Press Enter when done

Result in commit:

Co-authored-by: Jane Doe <jane@example.com>
Co-authored-by: John Smith <john@example.com>

4. References (Optional)

Link related issues or PRs:

  • Comma-separated
  • Supports: #123, PROJ-456, URLs

Examples:

#123
#123, #456
https://github.com/user/repo/issues/123
JIRA-456, #789

Result in commit:

Refs: #123
Refs: PROJ-456

5. Fixes Issues (Optional)

Automatically close issues:

  • Comma-separated
  • Automatically adds # prefix to plain numbers

Input: 123, 456
Result in commit:

Fixes: #123
Fixes: #456

Advanced Usage

Branch-Based Issue Detection

If your branch name contains an issue reference, GitWizard will automatically suggest it:

# Branch: feature/PROJ-123-add-login
# GitWizard detects: PROJ-123

Clipboard Integration

If your clipboard contains a URL or issue reference, GitWizard will suggest it as a reference.

GPG Signing

GitWizard respects your git configuration:

  • If you have GPG signing enabled, the passphrase prompt will appear
  • No special configuration needed

Edge Cases

No Staged Changes

If you haven't staged any files:

[!]  No changes staged for commit.
Would you like to stage all changes and commit? [y/N]

Merge in Progress

If a merge or rebase is in progress:

[!]  A merge or rebase is in progress.
Continue with commit? [y/N]

New Repository (No History)

GitWizard works even in brand new repositories:

  • Co-author list will be empty (no history to scrape)
  • All other features work normally

Not a Git Repository

[X] Error: not a git repository (or any parent directory)

Example Workflow

# 1. Make your changes
echo "console.log('hello');" > app.js

# 2. Stage files
git add app.js

# 3. Run GitWizard
gitwiz

# 4. Fill out the form:
#    Subject: Add hello world logging
#    Body: Initial implementation of logging system
#    Co-Authors: (select Jane Doe)
#    References: #123
#    Fixes: #456

# 5. Preview and confirm
[-] Commit Message Preview:
─────────────────────────
Add hello world logging

Initial implementation of logging system

Co-authored-by: Jane Doe <jane@example.com>
Refs: #123
Fixes: #456
─────────────────────────

Proceed with commit? [Y/n]

# 6. Success!
[OK] Commit successful! [*]

Configuration (Future Feature)

Create ~/.gitwiz.yaml to customize behavior:

custom_trailers:
  Reviewed-by: "Senior Dev <senior@example.com>"
  Ticket: "PROJ-123"

default_co_authors:
  - "Frequent Collaborator <collab@example.com>"

issue_patterns:
  - "PROJ-\\d+"
  - "TICKET-\\d+"

Troubleshooting

Command Not Found

# Ensure GitWizard is in your PATH
which gitwiz

# If not found, reinstall:
cd /path/to/gitwiz
./install.sh

GPG Passphrase Not Appearing

  • Ensure your terminal supports TTY input
  • Check git config --global gpg.program

Clipboard Not Working

  • Linux: Requires X11 or Wayland
  • macOS: Works out of the box
  • SSH/Remote: Clipboard features may not work

UI Rendering Issues

  • Requires UTF-8 terminal
  • Minimum terminal size: 80x24
  • Use a modern terminal emulator

Tips & Tricks

  1. Quick commits: For simple commits, just fill the subject and hit Enter through the rest

  2. Template commits: Always use the same co-authors? Set them in config (future feature)

  3. Conventional Commits: Add prefixes like feat:, fix:, docs: to your subjects

  4. Link everything: Always link to issues for better traceability

  5. Use the body: Future you (and your team) will thank you for explanations

Security Notes

  • GitWizard never executes user input as shell commands
  • All git operations use safe exec.Command() calls
  • Input is sanitized and validated before use

See SECURITY.md for detailed security information.