Skip to content

Commit c13dccf

Browse files
tsdevautsdevau
committed
docs(readme): add table of contents and configuration details
- Add detailed table of contents with section links - Expand command descriptions with keyboard shortcuts - Add detailed configuration section with default values and options - Restructure error handling section with status codes - Improve formatting and readability throughout document
1 parent 5169df0 commit c13dccf

File tree

1 file changed

+139
-39
lines changed

1 file changed

+139
-39
lines changed

‎README.md‎

Lines changed: 139 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,47 @@ Diff Commit is a VSCode extension that helps you generate commit messages follow
44

55
The generated commit messages are compatible with [googleapis/release-please](https://github.com/googleapis/release-please) and other tools that use conventional commits.
66

7+
## Table of Contents
8+
9+
- [Diff Commit](#diff-commit)
10+
- [Table of Contents](#table-of-contents)
11+
- [Features](#features)
12+
- [Requirements](#requirements)
13+
- [Installation](#installation)
14+
- [Typical Workflow](#typical-workflow)
15+
- [Commands](#commands)
16+
- [`DiffCommit: Generate Commit Message`](#diffcommit-generate-commit-message)
17+
- [DiffCommit: Generate Commit Message Default Keyboard Shortcuts](#diffcommit-generate-commit-message-default-keyboard-shortcuts)
18+
- [`DiffCommit: Preview Commit Message`](#diffcommit-preview-commit-message)
19+
- [DiffCommit: Preview Commit Message Default Keyboard Shortcuts](#diffcommit-preview-commit-message-default-keyboard-shortcuts)
20+
- [`DiffCommit: Update API Key`](#diffcommit-update-api-key)
21+
- [`DiffCommit: Delete API Key`](#diffcommit-delete-api-key)
22+
- [Configuration](#configuration)
23+
- [`diffCommit.allowedTypes`](#diffcommitallowedtypes)
24+
- [allowedTypes Default Value](#allowedtypes-default-value)
25+
- [allowedTypes Options](#allowedtypes-options)
26+
- [`diffCommit.customInstructions`](#diffcommitcustominstructions)
27+
- [customInstructions Default Value](#custominstructions-default-value)
28+
- [customInstructions Options](#custominstructions-options)
29+
- [`diffCommit.model`](#diffcommitmodel)
30+
- [model Default Value](#model-default-value)
31+
- [model Options](#model-options)
32+
- [`diffCommit.maxTokens`](#diffcommitmaxtokens)
33+
- [maxTokens Default Value](#maxtokens-default-value)
34+
- [maxTokens Range](#maxtokens-range)
35+
- [`diffCommit.temperature`](#diffcommittemperature)
36+
- [temperature Default Value](#temperature-default-value)
37+
- [temperature Range](#temperature-range)
38+
- [Error Handling](#error-handling)
39+
- [Git Related](#git-related)
40+
- [API Key Related](#api-key-related)
41+
- [Anthropic API Errors](#anthropic-api-errors)
42+
- [Other Errors](#other-errors)
43+
- [Local Development](#local-development)
44+
- [Local Testing](#local-testing)
45+
- [Contributing](#contributing)
46+
- [License](#license)
47+
748
## Features
849

950
- Generate commit messages based on the diff of staged changes using Anthropic's AI models like Claude 3.5 Sonnet
@@ -27,49 +68,108 @@ Install the extension directly from the [Visual Studio Code Marketplace](https:/
2768

2869
## Typical Workflow
2970

30-
1. Stage your changes in Source Control
31-
2. Open the Command Palette (<kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd>)
32-
3. Run the command: "DiffCommit: Generate Commit Message" (<kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>K</kbd> then <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>G</kbd>)
33-
4. Enter your Anthropic API key when prompted (_first time only_)
34-
5. Review the generated commit message in the Source Control message input
35-
6. Edit the commit message if necessary
36-
7. Click 'Commit' to commit the changes with the generated message
71+
1. Stage the changes that you wish to commit as normal
72+
2. Run the command: "DiffCommit: Generate Commit Message" (<kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>K</kbd> then <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>G</kbd>)
73+
3. Confirm or edit the generated commit message in the Source Control message input
74+
4. Click 'Commit' to commit the changes with the generated message
3775

3876
## Commands
3977

40-
Access DiffCommit commands from the Command Palette (<kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd>) or using the keyboard shortcuts:
78+
DiffCommit commands can be accessed from the Command Palette (<kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd>) or using the default keyboard shortcuts.
79+
80+
### `DiffCommit: Generate Commit Message`
81+
82+
This will generate a commit message for staged changes and enter it in the Source Control message input box. You can preview and edit the generated message before committing.
83+
84+
#### DiffCommit: Generate Commit Message Default Keyboard Shortcuts
85+
86+
- macOS: <kbd>Cmd</kbd> + <kbd>K</kbd> then <kbd>Cmd</kbd> + <kbd>G</kbd>
87+
- Windows/Linux: <kbd>Ctrl</kbd> + <kbd>K</kbd> then <kbd>Ctrl</kbd> + <kbd>G</kbd>
88+
89+
### `DiffCommit: Preview Commit Message`
90+
91+
This will generate a commit message for staged changes and open it in a new editor window. You can preview and edit the generated message before committing.
92+
93+
#### DiffCommit: Preview Commit Message Default Keyboard Shortcuts
94+
95+
- macOS: <kbd>Cmd</kbd> + <kbd>K</kbd> then <kbd>Cmd</kbd> + <kbd>P</kbd>
96+
- Windows/Linux: <kbd>Ctrl</kbd> + <kbd>K</kbd> then <kbd>Ctrl</kbd> + <kbd>P</kbd>
97+
98+
### `DiffCommit: Update API Key`
99+
100+
This will update the Anthropic API key used for API access. Enter your API key when prompted and press <kbd>Enter</kbd> to confirm or <kbd>Esc</kbd> to cancel.
41101

42-
- `DiffCommit: Generate Commit Message`: Generate a commit message for staged changes and enter it in the Source Control message input
43-
- macOS: <kbd>Cmd</kbd> + <kbd>K</kbd> then <kbd>Cmd</kbd> + <kbd>G</kbd>
44-
- Windows/Linux: <kbd>Ctrl</kbd> + <kbd>K</kbd> then <kbd>Ctrl</kbd> + <kbd>G</kbd>
45-
- `DiffCommit: Preview Commit Message`: Generate a commit message for staged changes and preview it in an editor window
46-
- macOS: <kbd>Cmd</kbd> + <kbd>K</kbd> then <kbd>Cmd</kbd> + <kbd>P</kbd>
47-
- Windows/Linux: <kbd>Ctrl</kbd> + <kbd>K</kbd> then <kbd>Ctrl</kbd> + <kbd>P</kbd>
48-
- `DiffCommit: Update API Key`: Update the Anthropic API key used for API access
49-
- `DiffCommit: Delete API Key`: Remove the stored Anthropic API key
102+
### `DiffCommit: Delete API Key`
103+
104+
This will delete the stored API key from your system and prevent DiffCommit from accessing the API in the future.
50105

51106
## Configuration
52107

53-
This extension provides the following settings:
54-
55-
- `diffCommit.allowedTypes`: List of allowed commit types. If provided, this replaces the default options.
56-
- Default: [ "feat", "fix", "refactor", "chore", "docs", "style", "test", "perf", "ci" ]
57-
- Options: Array<string>
58-
- `diffCommit.customInstructions`: Add additional custom instructions to the commit generation prompt. Useful for providing context or specific requirements like 'Use Australian English spelling'.
59-
- Default: ""
60-
- `diffCommit.model`: The Anthropic AI model to use for generating commit messages.
61-
- Default: "claude-3-5-sonnet-latest"
62-
- Options: "claude-3-opus-latest" | "claude-3-sonnet-20240229" | "claude-3-haiku-20240307"
63-
- `diffCommit.maxTokens`: Maximum number of tokens to generate in the response. Higher values allow for longer commit messages but use more API tokens.
64-
- Default: 1024
65-
- Range: 1 - 8192
66-
- `diffCommit.temperature`: Controls randomness in the response. Lower values (like 0.4) produce more focused and consistent commit messages, while higher values introduce more variety.
67-
- Default: 0.4
68-
- Range: 0 - 1
108+
DiffCommit provides the following settings to customise its behavior.
109+
110+
### `diffCommit.allowedTypes`
111+
112+
A list of allowed commit types. If provided, this replaces the default options.
113+
114+
#### allowedTypes Default Value
115+
116+
[ "feat", "fix", "refactor", "chore", "docs", "style", "test", "perf", "ci" ]
117+
118+
#### allowedTypes Options
119+
120+
**string[]** - A list (array) of any string you want to be able to use as a commit type.
121+
122+
### `diffCommit.customInstructions`
123+
124+
Add additional custom instructions to the commit generation prompt. Useful for providing context or specific requirements like 'Use Australian English spelling'.
125+
126+
#### customInstructions Default Value
127+
128+
""
129+
130+
#### customInstructions Options
131+
132+
**string** - Free formatted string that you want to included as custom instructions for the AI prompt.
133+
134+
### `diffCommit.model`
135+
136+
The Anthropic AI model to use for generating commit messages.
137+
138+
#### model Default Value
139+
140+
"claude-3-5-sonnet-latest"
141+
142+
#### model Options
143+
144+
**enum** - "claude-3-opus-latest" | "claude-3-sonnet-latest" | "claude-3-haiku-20240307"
145+
146+
### `diffCommit.maxTokens`
147+
148+
Maximum number of tokens to generate in the response. Higher values allow for longer commit messages but use more API tokens.
149+
150+
#### maxTokens Default Value
151+
152+
1024
153+
154+
#### maxTokens Range
155+
156+
**number** - 1 to 8192
157+
158+
### `diffCommit.temperature`
159+
160+
Controls randomness in the response. Lower values (like 0.4) produce more focused and consistent commit messages, while higher values introduce more variety.
161+
162+
#### temperature Default Value
163+
164+
0.4
165+
166+
#### temperature Range
167+
168+
**number** - 0 to 1
69169

70170
## Error Handling
71171

72-
Diff Commit includes comprehensive error handling to provide clear feedback and assist in troubleshooting. Here are the common error scenarios you might encounter:
172+
Diff Commit accommodates error handling to provide clear feedback and assist in troubleshooting. The following are the common warning or error scenarios you might encounter.
73173

74174
### Git Related
75175

@@ -86,19 +186,19 @@ Diff Commit includes comprehensive error handling to provide clear feedback and
86186

87187
### Anthropic API Errors
88188

89-
- Bad Request (400): Review your prompt and try again
90-
- Unauthorized (401): Invalid API key, please update and try again
91-
- Forbidden (403): Permission denied, review your API key
92-
- Rate Limited (429): Too many requests, try again later
93-
- Server Error (500): Anthropic API server error
189+
- **400** - Bad Request: Review your prompt and try again
190+
- **401** - Unauthorized: Invalid API key, update your API key and try again
191+
- **403** - Forbidden: Permission denied, update your API key and try again
192+
- **429** - Rate Limited: Too many requests, try again later
193+
- **500** - Server Error: Anthropic API server error
94194

95195
### Other Errors
96196

97197
- Failed to write commit message to Source Control
98198
- Failed to open commit message preview
99199
- No commit message was generated by the API
100200

101-
If you encounter any of these errors, the extension will display a message with more details. For persistent issues, please check your setup or raise an issue on [GitHub](https://github.com/tsdevau/diff-commit/issues).
201+
If you encounter any of these errors, the extension will display a message with more details. For persistent issues, please check your setup and if appropriate, raise an issue on [GitHub](https://github.com/tsdevau/diff-commit/issues).
102202

103203
## Local Development
104204

0 commit comments

Comments
 (0)