preguito

v0.2.3

Published

8 days ago

A lazy git CLI tool with commit templates and shortcuts

0High
0Medium
0Low

jacodoisdois

git cli commit template lazy

🦥 preguito

🌐 Landing Page | 📦 npm | 📚 Docs

A lazy git CLI with commit templates and shortcuts.

Typing the same commit prefix, squad name, and ticket number over and over is tedious. preguito lets you define a commit template once and reuse it on every commit — single-letter shortcodes replace verbose flags, so you only type what matters.

🔤 Single-letter shortcodes — f for feat, x for fix, p for prd
📝 Template-based commits — define once, reuse forever
⚡ Git shortcuts — commit, push, rebase, stash, undo in 2-3 chars
📁 Per-project config — .preguitorc in your repo for team conventions
📦 One dependency — just Commander.js, nothing else
🖥️ Standalone binary — works without Node.js via SEA

🎬 Quick Demo

Without preguito:

git add -A && git commit -m "[PAYMENTS-42] feat(prd): add login endpoint" && git push

With preguito:

guito c 42 fp "add login endpoint" -p
# → Committing: [PAYMENTS-42] feat(prd): add login endpoint
# ✔ Committed.
# ⠋ Pushing...
# ✔ Pushed.

42 is the card ID, f = feat, p = prd — everything else comes from your config.

📦 Installation

npm (requires Node.js >= 20)

npm install -g preguito

Standalone binary (.deb)

Download the .deb from GitHub Releases and install:

sudo dpkg -i preguito_0.2.2_amd64.deb

No Node.js required — the binary bundles everything via Node.js SEA.

🚀 Getting Started

1. Run the setup wizard

guito i

The wizard walks you through picking features, shortcodes, and creating your config:

✨ Welcome to preguito setup!

📋 Choose which features to enable:

  🎫 Include card/ticket ID in commits? (y/n): y
  🏷️  Include commit type (feat, fix, chore...)? (y/n): y
  🌍 Include environment (prd, uat, dev...)? (y/n): y

🔤 Project prefix/sigla (e.g. PROJ): PAYMENTS

─────────────────────────────────────
✅ Setup complete!

  📄 Config saved to /home/you/.config/preguito/config.json
  📝 Template: [PAYMENTS-{{card_id}}] {{type}}({{environment}}): <message>

  🔑 Your shortcodes:
     Types: f=feat, x=fix, c=chore, t=test, r=refactor, d=docs
     Envs:  p=prd, u=uat, d=dev, s=stg, l=local
─────────────────────────────────────

Or skip the wizard and use the default template:

guito i --default
# ✅ Config written to ~/.config/preguito/config.json
# Template: {{type}}: <message> (type defaults to feat)

2. Make your first commit

guito c 42 f "add login endpoint"
# → Committing: [PAYMENTS-42] feat: add login endpoint
# ✔ Committed.

With environment shortcode:

guito c 42 fp "add login endpoint"
# f = feat, p = prd
# → Committing: [PAYMENTS-42] feat(prd): add login endpoint
# ✔ Committed.

Commit and push in one go:

guito c 42 f "add login endpoint" -p
# → Committing: [PAYMENTS-42] feat: add login endpoint
# ✔ Committed.
# ⠋ Pushing...
# ✔ Pushed.

Preview without committing:

guito c 42 f "test message" -d
# [PAYMENTS-42] feat: test message

📋 Cheat Sheet

Commits

guito c 42 f "message"         # Templated commit
guito c 42 fp "message"        # With type + environment
guito c 42 f "message" -p      # Commit + push
guito c 42 f "message" -f      # Commit + force push (lease)
guito c 42 f "message" -d      # Dry run (preview only)
guito c 42 f "message" -S      # Skip auto-staging

Fixup

guito cf abc123                 # Fixup commit for abc123
guito cf abc123 -f              # Fixup + force push (lease)

Amend & Undo

guito ap                        # Amend + force push
guito apl                       # Amend + force push (lease)
guito u                         # Undo last commit (soft reset)
guito u 3                       # Undo last 3 commits

Branches & Stash

guito sw main                   # Switch branch
guito sw -n feature/login       # Create + switch
guito st                        # Stash changes
guito st -m "WIP login"         # Stash with message
guito stp                       # Stash pop
guito stl                       # List all stashes

Rebase

guito r main                    # Quick rebase on main
guito ri 3                      # Interactive rebase last 3
guito re abc123                 # Edit rebase at commit

Push

guito p                         # Simple push (git push)
guito pu                        # Push + set upstream

Diff

guito d                         # Show all changes
guito d -s                      # Show staged changes only
guito d --stat                  # Show diffstat summary
guito d -n                      # Show only changed file names

Inspect

guito s                         # Short status
guito l                         # Last 10 commits
guito l 20                      # Last 20 commits
guito f "login"                 # Search commits by message
guito t v1.0.0                  # Commits since tag
guito t v1.0.0 -a               # All commits reachable from tag

Config

guito i                         # Setup wizard
guito i --default               # Use default config
guito cfg                       # View current config
guito cfg --path                # Show config file path
guito cfg --template            # Show template only

🔤 Template System

Templates use {{variable}} for named parameters and <placeholder> for the commit message body.

[{{prefix}}-{{card_id}}] {{type}}({{environment}}): <message>

Variables are resolved from shortcodes first, then config defaults:

guito c 42 fp "add login"
# 42        → card_id
# f         → type = feat
# p         → environment = prd
# "add..."  → message
# → [PAYMENTS-42] feat(prd): add login

Shortcodes are single letters you define during guito i setup:

| Letter | Type | Letter | Environment | |--------|------|--------|-------------| | f | feat | p | prd | | x | fix | u | uat | | c | chore | d | dev | | t | test | s | stg | | r | refactor | l | local | | d | docs | | |

See template-system.md for full syntax, resolution order, and more examples.

🔧 Commands

| Command | Alias | Description | |---------|-------|-------------| | guito c [id] [codes] "msg" | commit | Templated commit with auto-stage | | guito cf <hash> | — | Create a fixup commit | | guito ap | — | Amend + force push | | guito apl | — | Amend + force push with lease | | guito u [count] | undo | Undo last N commits (soft reset) | | guito p | push | Simple push (git push) | | guito pu | — | Push with --set-upstream | | guito r <branch> | rebase | Quick rebase on branch | | guito re <hash> | — | Edit rebase at commit | | guito ri <count> | — | Interactive rebase last N commits | | guito sw <branch> | switch | Switch/create branch (-n to create) | | guito st | — | Stash changes (-m for message) | | guito stp | — | Pop latest stash | | guito stl | — | List all stashes | | guito d | diff | Show changes (-s staged, --stat, -n names) | | guito s | status | Short status | | guito l [count] | log | Compact log (default: 10) | | guito f <keyword> | find | Search commits by message | | guito t <tag> | tag | Commits since/from a tag | | guito i | init | Setup wizard | | guito cfg | config | View configuration |

See the full command reference for detailed usage, flags, and examples.

🔄 Common Workflows

Start a new feature

guito sw -n feature/login       # Create branch
# ... make changes ...
guito c 42 f "add login" -p     # Commit + push

Quick fix on current branch

# ... fix the bug ...
guito c 99 x "fix timeout" -p   # x = fix, push immediately

Oops, need to change the last commit

# ... make more changes ...
guito apl                        # Amend + force push (safe)

Rebase before opening a PR

guito r main                     # Pull main, rebase on top
guito pu                         # Push with upstream

Clean up commit history

guito ri 5                       # Interactive rebase last 5 commits
# or create fixup commits:
guito cf abc123 -f               # Fixup + force push

Review changes before committing

guito d                          # See all unstaged changes
guito d -s                       # See what's staged
guito d --stat                   # Quick summary of changed files
guito c 42 f "add feature" -p   # Commit + push

Stash work in progress

guito st -m "WIP: login page"    # Stash with a descriptive message
guito sw hotfix/urgent-fix       # Switch to another branch
# ... do urgent work ...
guito sw -                        # Switch back
guito stl                        # List stashes to find yours
guito stp                        # Restore your WIP

⚙️ Configuration

Config File Locations

preguito searches for config files in this order:

.preguitorc (project root)
.preguitorc.json (project root)
~/.preguitorc
~/.preguitorc.json
~/.config/preguito/config.json
Built-in default: {{type}}: <message> with type=feat

Project-local configs take priority, so different repos can use different templates.

Config Schema

{
  "template": "[PAYMENTS-{{card_id}}] {{type}}({{environment}}): <message>",
  "features": {
    "cardId": true,
    "type": true,
    "environment": true
  },
  "types": [
    { "key": "f", "label": "feat" },
    { "key": "x", "label": "fix" }
  ],
  "environments": [
    { "key": "p", "label": "prd" },
    { "key": "u", "label": "uat" }
  ],
  "defaults": {
    "prefix": "PAYMENTS"
  }
}

Per-Project Config

Place a .preguitorc or .preguitorc.json at your project root to share a commit convention with your team:

{
  "template": "[CHECKOUT-{{card_id}}] {{type}}: <message>",
  "features": { "cardId": true, "type": true, "environment": false },
  "types": [
    { "key": "f", "label": "feat" },
    { "key": "x", "label": "fix" },
    { "key": "c", "label": "chore" }
  ],
  "environments": [],
  "defaults": { "prefix": "CHECKOUT" }
}

The global config at ~/.config/preguito/config.json serves as your personal fallback.

📚 Programmatic API

preguito exports its core functions for use in other tools:

import {
  parseTemplate,
  renderTemplate,
  mergeContext,
  loadConfig,
  loadConfigOrDefault,
  writeConfig,
} from "preguito";

const parsed = parseTemplate("[{{squad}}] {{type}}: <message>");
// { variables: ["squad", "type"], messagePlaceholder: "message" }

const context = mergeContext({ type: "feat" }, { type: "fix" });
// { type: "fix" }

const msg = renderTemplate(
  "[{{squad}}] {{type}}: <message>",
  { squad: "TEAM", type: "fix" },
  "resolve timeout"
);
// "[TEAM] fix: resolve timeout"

❓ FAQ

Can I use preguito without running guito i first? Yes. Without a config, preguito uses the built-in default template {{type}}: <message> with type=feat. Just run guito c f "your message".

Can my team share a config? Yes. Place a .preguitorc or .preguitorc.json in your project root and commit it. Everyone on the team will use the same template and shortcodes.

Does it work without Node.js? Yes. Download the standalone .deb binary from GitHub Releases — it bundles everything via Node.js SEA.

What if I need different templates per project? Project-local config (.preguitorc in repo root) takes priority over global config. Each repo can have its own template, types, and environments.

Can I customize the shortcode letters? Yes. During guito i setup, you can reassign any letter to any type or environment. Run guito i again to reconfigure.

🤖 Claude Code Integration

preguito has an official Claude Code skill that teaches Claude the full guito command syntax, template system, and shortcodes.

npx skills add jacodoisdois/preguito-skill -g

Once installed, Claude Code will:

Automatically use guito c instead of git commit in preguito projects
Read your .preguitorc config to determine the correct shortcodes and card ID format
Offer a /guito-commit slash command for interactive commit crafting with dry-run preview

🤝 Contributing

git clone https://github.com/jacodoisdois/preguito.git
cd preguito/packages/preguito
npm install

| Script | Description | |--------|-------------| | npm run dev | Watch mode (tsdown) | | npm test | Run tests (vitest) | | npm run lint | Type check (tsc --noEmit) | | npm run build | Production build | | npm run build:sea | Build standalone binary (Node.js SEA) | | npm run build:deb | Build .deb package |

Tech stack: TypeScript, Commander.js, tsdown (Rolldown-based bundler), Vitest.

📄 License

MIT