User Guide

User Guide

Opening the Editor

You can open the editor in several ways:

Method	Action
Source Control panel	Click the edit icon (pencil) in the top-right corner
Command Palette	Ctrl+Shift+P → Git Commit Message Editor: Open Editor
Command Palette	Git Commit Message Editor: Open in New Tab (full-width)
Status Bar	Click the $(edit) Commit Msg item

Interface Overview

+--------------------------------------------------+
| Dashboard (sticky chips + progress + warnings)    |
+--------------------------------------------------+
| Header: "Commit Message Editor — <template name>" |
| Source badge (extension / repo file)              |
+--------------------------------------------------+
| Toolbar: Insert | Copy | Reset | Suggestions | … |
+--------------------------------------------------+
| AI status line                                    |
+--------------------------------------------------+
| Form (left pane)          | Preview (right pane)  |
|                           |                       |
|   Type grid (with emojis) | .git/COMMIT_EDITMSG  |
|   Scope                   | (line numbers + text) |
|   Subject                 |                       |
|   Body                    | Character / line      |
|   Additional details …    | count                |
|   Optional sections …     |                       |
|                           | Recent commits        |
+--------------------------------------------------+

Dashboard (Status Strip)

• Chips – one for each field (core and optional)
  • 🟢 green = field is filled
  • 🔴 red = required field is empty
  • ⚪ grey = optional and not filled
• Click any chip to focus that field
• Progress counter – shows how many fields are filled
• Warnings – click to jump to the first invalid field

Toolbar

Button	Description
Insert	Writes the message into the Source Control input box
Copy	Copies the message to the clipboard
Reset	Clears all form fields
⚡ Suggestions	Fills empty fields with smart guesses
⋮ More	Opens a dropdown with additional actions

More Menu

Item	Description
✨ AI Draft	Generates a draft from staged changes using Copilot Chat
⚙ Template	Opens the Config Editor
📌 Git Template	Writes to .gitmessage and sets commit.template
🔄 Amend Last	Loads the last commit's message into the form
↩️ Undo Insert	Restores the previous SCM input box value
📁 Repo Config	Creates a starter .commit-message-editor.json

Filling the Form

Core Fields

• Type – Grid of labels (feat, fix, docs, etc.). Click to select; click again to clear.
• Scope – Text field with ➕ Save button to save new scopes as clickable chips.
• Subject – Short summary. Live validation warns about length, trailing period, capitalisation, and imperative mood.
• Body – Multiline textarea. Warnings for lines exceeding maxLineLength.

Additional Details

All optional single-line fields appear in a compact grid:

• Closes, Resolves, Refs, See also – comma-separated issue numbers (automatically adds #)
• Signed-off-by – ⇩ Git button fetches from git config

Optional Sections

Conditional fields (e.g., BREAKING CHANGE) automatically expand when you type and collapse when empty.

Smart Suggestions

Click ⚡ Suggestions to auto-fill empty fields:

• Scope – guessed from the top-level folder of staged files
• Resolves – extracted from branch name (e.g., feature/JIRA-123)
• Signed-off-by – from git config (if autoFillSignedOffBy is enabled)

AI Draft

Requires GitHub Copilot Chat installed and signed in:

1. Stage some changes (git add)
2. Click ✨ AI Draft
3. The extension analyses the diff and fills the form

Recent Commits

Click any recent commit to load its subject and body into the form – the editor automatically parses type, scope, Gitmoji, and trailers.

Free‑form Text Mode

You can switch between the structured Form mode and a Free‑form Text mode using the tabs at the top of the form.

• In Form mode, you fill out individual fields (Type, Scope, Subject, etc.) and the message is assembled automatically.
• In Free‑form Text mode, you write the entire commit message in a single large textarea. The editor attempts to parse it into the corresponding form fields, and the preview updates in real time.

Lines starting with # are ignored as comments. The first line is treated as the subject, and the rest as the body. Validation rules (length, trailing period, capitalisation, imperative mood) are applied to the first line.

Git Editor Mode (COMMIT_EDITMSG)

This mode opens a full VS Code editor for writing your commit message, similar to git commit from the terminal.

• Opening: Use the Command Palette (Git Commit Message Editor: Open as Git Editor (COMMIT_EDITMSG)) or set scmTitleCommand to "openAsGitEditor" to replace the SCM icon.
• Features:
  • Full VS Code editing capabilities (syntax highlighting, autocomplete, extensions).
  • 50/72 rulers are automatically configured.
  • Lines starting with # are treated as comments and ignored.
  • The message is automatically applied to the Source Control input box when you save (Ctrl+S).
• Configuration: Disable auto‑apply by setting autoApplyGitEditor to false.

Advanced Issue References

In fields like Closes, Resolves, Refs, and See also, you can use GitHub's autolinked reference formats:

• #123 – issue in the same repository
• GH-123 – alternative prefix
• owner/repo#123 – issue in another repository

You can also combine multiple issues with different keywords in one field:

Supported keywords: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved.