Function Signatures
The commit function has multiple overloads to support different usage patterns:
// Simple commit with message
function commit(
message: string | undefined,
description?: string
): Promise<string>
// Commit with options
function commit(
message: string | undefined,
opts?: CommitOptions
): Promise<string>
// Commit with message, description, and options
function commit(
message: string | undefined,
description?: string,
opts?: CommitOptions
): Promise<string>
Parameters
message
string | undefined
required
The commit message (first line). This becomes the subject line of the commit.Can be undefined when using options like --reuse-message or --fixup.
Optional extended description for the commit. This becomes the body of the commit message.Provides additional context and details about the changes.
opts
CommitOptions
default:"{}"
Configuration options for the commit operation.Show CommitOptions properties
Additional flags to pass to git commit. Supported flags:
"--amend" - Amend the previous commit"--no-verify" - Bypass pre-commit and commit-msg hooks"--signoff" - Add Signed-off-by trailer"--no-edit" - Use the selected commit message without launching an editor"--all" - Automatically stage modified and deleted files"--patch" - Use interactive patch selection"--allow-empty" - Allow commit with no changes"--allow-empty-message" - Allow commit with empty message"--quiet" - Suppress commit summary message"--status" - Include git status in commit message template"--no-status" - Do not include git status in commit message template"--reset-author" - Reset author to committer info
Override the commit author.Format: "Name <email>"Example: "Alice <[email protected]>" Override the author date used in the commit.Accepts various formats:
"2024-01-01""yesterday"- RFC 2822 or ISO 8601 format
--cleanup
'strip' | 'whitespace' | 'verbatim' | 'scissors' | 'default'
How to clean up the commit message:
"strip" - Remove leading/trailing whitespace and comments"whitespace" - Remove leading/trailing whitespace"verbatim" - Do not change the message"scissors" - Remove everything after scissor line"default" - Use configured default
--untracked-files
'no' | 'normal' | 'all'
default:"'all'"
Show untracked files:
"no" - Show no untracked files"normal" - Show untracked files and directories"all" - Show individual files in untracked directories
Use a commit message template file.Path to a template file for the commit message.
Take commit message from file or stdin ("-").
GPG-sign the commit.
true - Sign with default keystring - Sign with specific key ID
Examples:
"--gpg-sign": true → --gpg-sign"--gpg-sign": "ABC123" → --gpg-sign=ABC123
Construct commit message for squashing with specified commit.
Reuse message from specified commit.Use the commit message and authorship from the given commit.
Create a fixup commit for the specified commit.Used with interactive rebase autosquash.
Returns
A promise that resolves to the output from the git commit command, typically including the commit hash and summary.
Examples
Basic commits
import { add, commit } from "usegit"
// Stage and commit files
await add(".")
await commit("feat: add new API")
Commit with description
// Commit with extended description
await commit(
"fix: handle empty input",
"This fixes a bug where empty input caused a crash."
)
Commit with options
// Amend the last commit
await commit("chore: release", { flags: ["--amend"] })
// Commit with signoff
await commit("feat: improve API", {
flags: ["--signoff"]
})
Commit with description and options
// All three parameters
await commit(
"feat: improve API",
"Adds better typing and docs.",
{ flags: ["--signoff"] }
)
Advanced options
// Commit with custom author
await commit("feat: initial import", {
"--author": "Alice <[email protected]>"
})
// Commit with custom date
await commit("fix: backdate", {
"--date": "2024-01-01"
})
// GPG-signed commit
await commit("feat: secure feature", {
"--gpg-sign": true
})
// GPG-signed with specific key
await commit("feat: secure feature", {
"--gpg-sign": "ABC123DEF456"
})
Allow empty commits
// Create commit without changes (useful for CI triggers)
await commit("chore: trigger CI", {
flags: ["--allow-empty"]
})
Bypass hooks
// Skip pre-commit hooks
await commit("fix: urgent", {
flags: ["--no-verify"]
})