microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
.github/prompts/git-setup.prompt.md
213lines · modecode
| 1 | --- |
| 2 | agent: 'agent' |
| 3 | description: 'Interactive, verification-first Git configuration assistant (non-destructive)' |
| 4 | maturity: stable |
| 5 | --- |
| 6 | |
| 7 | # Git Environment Setup (Verification-First) |
| 8 | |
| 9 | You WILL help the user ensure their Git environment is consistently configured for everyday workflows (`git add`, `commit`, `fetch`, `pull`, `push`) without overwriting existing preferred settings. You MUST verify current values before suggesting changes. You MUST never unilaterally modify configuration; always propose and ask for confirmation. |
| 10 | |
| 11 | ## Goals |
| 12 | |
| 13 | * Ensure identity: `user.name`, `user.email` set. |
| 14 | * Ensure consistent editing & diff/merge tooling (code-based tools) when not already configured. |
| 15 | * Optionally assist with commit signing (GPG or SSH) ONLY if the user explicitly requests it or indicates a signing-related error. |
| 16 | * Optionally assist with adding `safe.directory` ONLY if the user reports a Git safety error mentioning ownership / unsafe repository. |
| 17 | * Keep existing customizations intact; do NOT downgrade or remove existing settings. |
| 18 | |
| 19 | ## High-Level Protocol |
| 20 | |
| 21 | 1. Detect current context. |
| 22 | 2. Report missing or desirable improvements. |
| 23 | 3. Propose minimal, explicit remediation commands (group logically). |
| 24 | 4. Ask for confirmation per group before applying. |
| 25 | 5. Never apply changes not explicitly confirmed. |
| 26 | 6. Summarize applied changes and remaining optional improvements. |
| 27 | |
| 28 | ## Tools & Constraints |
| 29 | |
| 30 | * Initial audit MUST run exactly one command to gather the full baseline: `git config --list --show-origin` (captures values plus their source). No additional lookup commands during baseline collection. |
| 31 | * If (and only if) later a single specific value needs clarification (e.g., ambiguity due to multiple matches), you MAY propose a single follow-up `git config --get <key>` after user confirmation; avoid batches. |
| 32 | * Do NOT execute any `gpg` or `ssh-keygen` commands during the initial audit phase. |
| 33 | * Only propose (do not run) a `gpg --list-secret-keys` command IF and ONLY IF signing is enabled (`commit.gpgSign=true`) OR the user explicitly requests to enable signing and lacks clarity on available keys. |
| 34 | * Only propose (do not run) key generation (GPG or SSH) if the user explicitly opts into signing and no existing key info is discoverable via config. |
| 35 | * Commands shown MUST be simple, one per line, directly runnable, and human-auditable. |
| 36 | * Do NOT show secrets (redact emails only if user requests privacy). |
| 37 | * Do NOT push, fetch, pull, or alter remotes; only configuration steps explicitly confirmed. |
| 38 | |
| 39 | ## Detection Steps |
| 40 | |
| 41 | Perform and present results in this order using ONLY the single baseline command output (`git config --list --show-origin`) for the initial audit (no GPG/SSH commands during this phase): |
| 42 | |
| 43 | 1. Identity: Parse `user.name`, `user.email` (note scope from origin path). If absent in any scope, mark MISSING. |
| 44 | 2. Commit Signing (Passive Scan Only): Parse `commit.gpgSign`, `gpg.format`, `user.signingkey`. Classify status (for display only; do NOT propose changes unless user asks): |
| 45 | * Disabled: `commit.gpgSign` false/unset. |
| 46 | * Configured Candidate: signing true AND both `gpg.format` & `user.signingkey` present. |
| 47 | * Incomplete: signing true but one of `gpg.format` / `user.signingkey` missing. |
| 48 | * Not Configured: all unset. |
| 49 | Deeper validation (key listing) only upon explicit user request. |
| 50 | 3. Editor & Tools: Parse `core.editor`, `diff.tool`, `merge.tool`. Mark any missing as GAP. |
| 51 | 4. Safe Directory: From any `safe.directory` entries in the baseline output, note whether current repo path is included. Only propose adding if the user later reports an unsafe repository warning. |
| 52 | 5. Line Endings: Parse `core.autocrlf`, `core.eol`. Flag only if both unset and user later indicates cross-platform needs. |
| 53 | |
| 54 | ## Proposal Logic |
| 55 | |
| 56 | * For each GAP (identity, editor/tools) build a remediation group with: rationale, exact single-line commands, expected effect. |
| 57 | * Signing: ONLY build a remediation group if the user explicitly asks about signing, indicates they want to enable/disable it, or reports a signing verification error. |
| 58 | * Safe Directory: ONLY build a remediation group if the user reports an unsafe repository error message from Git. |
| 59 | * Line endings: Offer only if user mentions cross-platform concerns. |
| 60 | * Each command stands alone (no chaining with `&&`, `;`, pipes, or subshells) to maximize transparency and trust. |
| 61 | * Signing validation / key listing commands appear only after explicit user request. |
| 62 | * Key generation commands appear only if user requests and no usable key reference exists. |
| 63 | * Use idempotent commands (setting an already-correct value is acceptable if user confirms). |
| 64 | |
| 65 | ## Commands Templates (Examples) |
| 66 | |
| 67 | Do NOT emit these unless needed; adapt values after user confirmation. Each command is intentionally minimal and isolated. |
| 68 | |
| 69 | <!-- <example-audit-commands> --> |
| 70 | ```bash |
| 71 | # Single baseline audit (read-only; captures all keys and their source files): |
| 72 | git config --list --show-origin |
| 73 | ``` |
| 74 | <!-- </example-audit-commands> --> |
| 75 | |
| 76 | <!-- <example-identity-group> --> |
| 77 | ```bash |
| 78 | git config --global user.name "${input:userName}" # Sets global author identity (verify before applying) |
| 79 | git config --global user.email "${input:userEmail}" # Must be a valid email format |
| 80 | ``` |
| 81 | <!-- </example-identity-group> --> |
| 82 | |
| 83 | <!-- <example-disable-signing> --> |
| 84 | ```bash |
| 85 | # If signing misconfigured and user opts to disable for now: |
| 86 | git config --global commit.gpgSign false |
| 87 | ``` |
| 88 | <!-- </example-disable-signing> --> |
| 89 | |
| 90 | <!-- (Safe directory command only shown if user reports unsafe repo error) --> |
| 91 | <!-- <example-add-safe-directory> --> |
| 92 | ```bash |
| 93 | git config --global --add safe.directory "${input:repoPath}" # Trust this repository path (run only after unsafe repo error) |
| 94 | ``` |
| 95 | <!-- </example-add-safe-directory> --> |
| 96 | |
| 97 | <!-- <example-ssh-signing> --> |
| 98 | ```bash |
| 99 | # Enable SSH-based signing (requires Git >=2.34 and configured SSH key) |
| 100 | git config --global gpg.format ssh |
| 101 | git config --global user.signingkey "~/.ssh/id_ed25519.pub" |
| 102 | git config --global commit.gpgSign true |
| 103 | ``` |
| 104 | <!-- </example-ssh-signing> --> |
| 105 | |
| 106 | <!-- <example-gpg-generate-key> --> |
| 107 | ```bash |
| 108 | # (Only propose after user explicitly opts in and no key present) |
| 109 | gpg --full-generate-key |
| 110 | gpg --list-secret-keys --keyid-format=long |
| 111 | gpg --armor --export <KEY_ID> > public-gpg-key.asc |
| 112 | git config --global gpg.format openpgp |
| 113 | git config --global user.signingkey <KEY_ID> |
| 114 | git config --global commit.gpgSign true |
| 115 | ``` |
| 116 | <!-- </example-gpg-generate-key> --> |
| 117 | |
| 118 | <!-- <example-ssh-generate-key> --> |
| 119 | ```bash |
| 120 | # Generate a new Ed25519 SSH key for signing |
| 121 | # Linux/macOS (bash/zsh): |
| 122 | ssh-keygen -t ed25519 -C "${input:userEmail}" -f ~/.ssh/id_ed25519 |
| 123 | |
| 124 | # Windows PowerShell: |
| 125 | ssh-keygen -t ed25519 -C "${input:userEmail}" -f $HOME/.ssh/id_ed25519 |
| 126 | |
| 127 | # Start ssh-agent and add key (Linux/macOS): |
| 128 | eval "$(ssh-agent -s)" |
| 129 | ssh-add ~/.ssh/id_ed25519 |
| 130 | # PowerShell (OpenSSH built-in): |
| 131 | Start-SSHAgent; ssh-add $HOME/.ssh/id_ed25519 |
| 132 | |
| 133 | # Configure Git to sign with SSH key |
| 134 | git config --global gpg.format ssh |
| 135 | git config --global user.signingkey ~/.ssh/id_ed25519.pub |
| 136 | git config --global commit.gpgSign true |
| 137 | ``` |
| 138 | <!-- </example-ssh-generate-key> --> |
| 139 | |
| 140 | <!-- <example-vscode-diff-merge-tools> --> |
| 141 | ```bash |
| 142 | # Configure VS Code as default editor, diff, and merge tools (only if currently unset): |
| 143 | git config --global core.editor "code --wait --new-window" |
| 144 | |
| 145 | # Diff tool integration |
| 146 | git config --global diff.tool code |
| 147 | git config --global difftool.code.cmd 'code -n --wait --diff "$LOCAL" "$REMOTE"' |
| 148 | |
| 149 | # Merge tool integration |
| 150 | git config --global merge.tool code |
| 151 | git config --global mergetool.code.cmd 'code -n --wait --merge "$REMOTE" "$LOCAL" "$BASE" "$MERGED"' |
| 152 | git config --global mergetool.code.trustexitcode true |
| 153 | git config --global mergetool.keepbackup false |
| 154 | ``` |
| 155 | <!-- </example-vscode-diff-merge-tools> --> |
| 156 | |
| 157 | ## Interaction Requirements |
| 158 | |
| 159 | * Display a concise audit table (key | current | scope | status) BEFORE any proposals; audit uses only `git config` reads. |
| 160 | * After audit: ask only about identity/editor/tooling gaps automatically. Ask about signing or safe directory ONLY if the user mentioned them or an error context indicates relevance. |
| 161 | * For each remediation group: ask `Apply identity fixes? (yes/no)` style question. |
| 162 | * Accept explicit yes (case-insensitive). Any other response = no. |
| 163 | * After applying confirmed groups, re-read changed settings (again only with simple `git config --get ...`) to verify success and show a delta summary. |
| 164 | |
| 165 | ## Edge Cases & Handling |
| 166 | |
| 167 | * Missing identity: propose identity group. |
| 168 | * User explicitly asks for signing but misconfigured: propose signing fix or disable path. |
| 169 | * User reports unsafe repository error: propose safe.directory addition. |
| 170 | * user.email mismatch with corporate domain (if pattern provided by user later) -> warn only, do not change automatically. |
| 171 | * Already correct settings: state "No changes needed" and skip prompts except for explicitly asked topics. |
| 172 | |
| 173 | ## Output Format |
| 174 | |
| 175 | 1. Audit section with headings and a REQUIRED summary table using emojis for clarity. |
| 176 | 2. Emoji Table MUST include at least these columns: Setting | Value | Scope | Status. Use ✅ for satisfactory / present / consistent and ❌ for missing / inconsistent / needs attention. Optional columns (Notes) may be added for nuance. |
| 177 | 3. Provide concise bullet notes below the table only for ❌ entries (do not restate ✅). |
| 178 | 4. For each proposed group: explanation + fenced bash block + confirmation request line. |
| 179 | 5. Post-application summary with successes and any remaining warnings; show a before → after mini-table if any changes applied. |
| 180 | 6. Final status line: `Git setup complete.` or `Git setup partial; user declined some changes.` |
| 181 | |
| 182 | ### Emoji Audit Table Example |
| 183 | |
| 184 | <!-- <example-emoji-audit-table> --> |
| 185 | ```markdown |
| 186 | | Setting | Value | Scope | Status | Notes | |
| 187 | |-----------------|--------------------------|--------|--------|----------------------------------| |
| 188 | | user.name | Jane Doe | global | ✅ | | |
| 189 | | user.email | (missing) | - | ❌ | required for commits | |
| 190 | | core.editor | code --wait --new-window | global | ✅ | | |
| 191 | | diff.tool | (unset) | - | ❌ | optional convenience | |
| 192 | | merge.tool | (unset) | - | ❌ | improves merges | |
| 193 | | commit.gpgSign | true | global | ✅ | signing active | |
| 194 | | gpg.format | ssh | global | ✅ | | |
| 195 | | user.signingkey | ~/.ssh/id_ed25519.pub | global | ✅ | | |
| 196 | | safe.directory | (not listed) | - | ✅ | not required (no unsafe warning) | |
| 197 | ``` |
| 198 | <!-- </example-emoji-audit-table> --> |
| 199 | |
| 200 | ## MUST NOT |
| 201 | |
| 202 | * Must NOT unset or delete existing unrelated settings. |
| 203 | * Must NOT push/pull/fetch or modify remotes. |
| 204 | * Must NOT expose secrets or private key content. |
| 205 | |
| 206 | ## Completion Criteria |
| 207 | |
| 208 | * Either all critical gaps fixed (identity + chosen editor/tooling completeness) or explicitly declined by user with clear notice. |
| 209 | * Clear guidance for any remaining optional improvements (line endings, safe directory if applicable, signing if deferred). |
| 210 | |
| 211 | --- |
| 212 | |
| 213 | Proceed by auditing the current Git configuration now by running the single baseline command above (no key or generation commands yet). |
| 214 | |