Preguito Skill

preguito (CLI name: guito) is a lazy Git CLI with commit templates and shortcode expansion. When working in a preguito project, always prefer guito commands over raw git equivalents.

Detecting a Preguito Project

A project uses preguito if any of these files exist:

• .preguitorc (project root)
• .preguitorc.json (project root)
• ~/.config/preguito/config.json (global user config)

Before crafting a commit, read the config to discover the template and shortcodes:

cat .preguitorc 2>/dev/null || cat .preguitorc.json 2>/dev/null

Config Schema

{
  "template": "{{type}}: <message>",
  "features": {
    "cardId": false,
    "type": true,
    "environment": false
  },
  "types": [
    { "key": "f", "label": "feat" },
    { "key": "x", "label": "fix" },
    { "key": "c", "label": "chore" },
    { "key": "t", "label": "test" },
    { "key": "r", "label": "refactor" },
    { "key": "o", "label": "docs" }
  ],
  "environments": [],
  "defaults": {}
}

Key fields:

• template — Mustache-style; {{var}} variables + <message> placeholder
• features.cardId — If true, first positional arg to guito c is the card/ticket ID
• features.type — If true, shortcodes arg must include exactly one type letter
• features.environment — If true, shortcodes arg may include one environment letter
• defaults — Merged into template context automatically (e.g. { "prefix": "PROJ" })

Template Rendering Rules

Variables use {{varname}} syntax. The <message> placeholder is replaced by the commit message. Optional variables that resolve to empty string trigger cleanup:

• () → removed entirely
• [] → removed entirely
• {} → removed entirely
• Multiple spaces → single space
• Space before colon → removed: feat : msg → feat: msg

Common generated templates (from generateTemplate()):

Features enabled	Template
type only	{{type}}: <message>
cardId + type	[{{card_id}}] {{type}}: <message>
cardId + prefix + type	[{{prefix}}-{{card_id}}] {{type}}: <message>
type + environment	{{type}}({{environment}}): <message>
cardId + type + environment	[{{card_id}}] {{type}}({{environment}}): <message>
environment only	({{environment}}): <message>

Command Syntax: guito c

guito c [card_id] [shortcodes] <message...> [flags]

Positional argument order is strict and depends on enabled features:

1. card_id — first arg, only if features.cardId is true (any string: "42", "PROJ-42")
2. shortcodes — concatenated single string, only if features.type or features.environment is true
3. message — everything remaining, joined with spaces (no quotes required for multiple words)

Flags

Flag	Long	Description
-p	--push	Push after committing
-f	--force	Push with --force-with-lease after committing
-d	--dry-run	Print generated message without executing
-S	--no-stage	Skip auto-staging (git add -A). By default, all changes are staged automatically

Shortcode Resolution

Each character in the shortcodes string is independently resolved:

• Matches a types key → sets type in context
• Matches an environments key → sets environment in context
• Exactly one type shortcode required if features.type is true
• At most one environment shortcode; environment is always optional
• Character matching both type and env → ambiguity error
• Character matching neither → unknown shortcode error

Default Type Shortcodes

Key	Label	When to use
f	feat	New feature or capability
x	fix	Bug fix
c	chore	Maintenance, deps, config
t	test	Adding or modifying tests
r	refactor	Code restructuring, no behavior change
o	docs	Documentation
l	lint	Linting fixes
y	style	Code style / formatting
e	perf	Performance improvement
b	build	Build system / scripts

Default Environment Shortcodes

Key	Label
p	prd
u	uat
h	homolog
d	dev
s	staging

Complete Examples by Feature Combination

Config: type only (default config)

guito c f "add user authentication"
# → feat: add user authentication

guito c x "fix null pointer in login" -p
# → fix: fix null pointer in login  (then pushes)

guito c r "extract service layer" -d
# dry-run → prints: refactor: extract service layer

Config: cardId + type

guito c 42 f "add user authentication"
# → [42] feat: add user authentication

guito c PROJ-123 r "extract service layer"
# → [PROJ-123] refactor: extract service layer

guito c 99 c "update dependencies" -p
# → [99] chore: update dependencies  (then pushes)

Config: cardId + type + environment

guito c 42 fp "deploy payment gateway"
# → [42] feat(prd): deploy payment gateway

guito c 77 xd "fix timeout bug" -p
# → [77] fix(dev): fix timeout bug  (then pushes)

guito c 10 fu "release to uat"
# → [10] feat(uat): release to uat

Config: type + environment (no cardId)

guito c fp "deploy login service"
# → feat(prd): deploy login service

guito c xs "fix staging crash"
# → fix(staging): fix staging crash

Config: cardId + prefix in defaults

{ "defaults": { "prefix": "TASK" }, "template": "[{{prefix}}-{{card_id}}] {{type}}: <message>" }

guito c 55 f "add export endpoint"
# → [TASK-55] feat: add export endpoint

All Other Commands

guito p — Push

Alias: push

guito p       # git push
guito push    # same

guito pu — Push upstream

guito pu      # git push --set-upstream origin <current-branch>

Use on first push of a new branch.

---

guito r <branch> — Rebase

Alias: rebase

guito r main          # checkout main → pull → rebase current branch onto main → back
guito rebase develop  # same with alias

Runs the full rebase workflow in one command: checkout <branch> → pull → go back → rebase <branch>.

---

guito ri <count> — Interactive rebase

guito ri 3    # git rebase -i HEAD~3  (interactive for last 3 commits)
guito ri 5    # last 5 commits

---

guito re <hash> — Edit rebase at commit

guito re abc1234   # sets GIT_SEQUENCE_EDITOR to mark that commit as "edit"

---

guito ap — Amend + force push

guito ap    # git commit --amend --no-edit && git push --force

Use when you need to update the last commit and force push. Prefer guito apl for shared branches.

---

guito apl — Amend + force-with-lease push

guito apl   # git commit --amend --no-edit && git push --force-with-lease

Safer than guito ap — fails if the remote has new commits that you haven't fetched, preventing accidental overwrites.

---

guito u [count] — Undo commits

Alias: undo

guito u       # undo last 1 commit, keep changes staged (git reset --soft HEAD~1)
guito u 3     # undo last 3 commits, keep all changes staged
guito undo 2  # same with alias

Changes remain staged after undo — you can re-commit or amend them.

---

guito cf <hash> — Fixup commit

Flag	Description
-p / --push	Push after creating fixup
-f / --force	Push with --force-with-lease after fixup

guito cf abc1234         # git commit --fixup=abc1234
guito cf abc1234 -p      # fixup then push
guito cf abc1234 -f      # fixup then force-with-lease push

---

guito sw <branch> — Switch branch

Alias: switch

Flag	Description
-n / --new	Create the branch if it doesn't exist

guito sw main              # git checkout main
guito sw -n feature/login  # git checkout -b feature/login
guito switch develop        # same with alias

---

guito st — Stash

Flag	Description
-m / --message <msg>	Label for the stash entry

guito st                          # git stash
guito st -m "work in progress"    # git stash push -m "work in progress"

---

guito stp — Stash pop

guito stp    # git stash pop

---

guito stl — Stash list

guito stl    # git stash list

---

guito s — Status

Alias: status

guito s       # git status --short
guito status  # same

---

guito d — Diff

Alias: diff

Flag	Description
-s / --staged	Show only staged changes (git diff --staged)
--stat	Summary view with file names and change counts
-n / --name-only	Show only changed file names

guito d              # git diff (unstaged changes)
guito d -s           # git diff --staged
guito d --stat       # git diff --stat
guito d -n           # git diff --name-only
guito diff --staged  # same as -s, with alias

---

guito l [count] — Log

Alias: log

guito l       # last 10 commits, oneline format
guito l 5     # last 5 commits
guito l 25    # last 25 commits
guito log     # same with alias

---

guito f <keyword> — Find commits

Alias: find

Flag	Description
-n / --number <count>	Limit number of results

guito f "login"         # search all commits mentioning "login"
guito f "feat" -n 5     # last 5 commits mentioning "feat"
guito find "fix"        # same with alias

---

guito t <tag> — Commits since tag

Alias: tag

Flag	Description
-a / --all	Include all commits reachable from tag

guito t v1.0.0         # commits since v1.0.0
guito t v1.0.0 -a      # all commits reachable from v1.0.0
guito tag v0.2.0        # same with alias

---

guito cfg — Show config

Alias: config

Flag	Description
--path	Print only the config file path
--template	Print only the template string

guito cfg             # show full config (features, types, environments, template)
guito cfg --path      # /home/user/.config/preguito/config.json
guito cfg --template  # {{type}}: <message>
guito config          # same with alias

---

guito i — Init wizard

Alias: init

Flag	Description
--default	Skip prompts and write default config immediately

guito i            # interactive setup: choose features, shortcodes, prefix
guito i --default  # write default config (type-only) without prompts
guito init         # same with alias

How to Help Users Craft Commits

1. Check if .preguitorc or .preguitorc.json exists
2. Parse template and features from the config
3. Determine what positional args are needed (cardId → shortcodes → message)
4. Map the user's description to the appropriate type shortcode
5. Build the guito c invocation
6. Always show dry-run first: guito c ... -d
7. Execute when the user confirms

Common Mistakes to Avoid

• NEVER use git commit -m "..." in preguito projects — always use guito c
• NEVER use git push — use guito p
• NEVER invent shortcodes — read from the config's types array
• NEVER separate shortcodes with spaces — f p is wrong, fp is correct
• NEVER chain multiple types — fx means feat+fix which is invalid; one type only
• Shortcodes arg is one concatenated string: fp not f p
• Auto-staging is ON by default — no need to git add before guito c unless using -S