git component functions #
Requires FluentCI v0.17.3 or newer. The compiler derives native WIT signatures and embedded help from these typed PureScript functions. Optional arguments may be omitted.
setup #
Ensure git is installed and verified, reusing an available matching version, and publish its environment.
| Argument | Type | Required | Description |
|---|---|---|---|
version |
string |
no | Tool release or supported channel to install; omitted values use the documented default. |
install-dir |
string |
no | Absolute per-user installation prefix; omit for native package installations. |
package-name |
string |
no | Native package or port selector overriding the default repository package name. |
sudo |
boolean |
no | Use noninteractive sudo for native package or system installation; defaults to false. |
Returns Contract.SetupResult.
run #
Run any native git command with literal argv.
| Argument | Type | Required | Description |
|---|---|---|---|
project |
string |
no | Working directory containing the source checkout; defaults to the current directory. Default: ".". |
run-dir |
string |
yes | Fresh directory for this invocation’s execution report and task logs; must not already exist. |
executable |
string |
no | Native CLI executable name or absolute path; defaults to this operation’s tool. |
timeout-ms |
integer |
no | Maximum task duration in milliseconds; defaults to 900000. Default: 900000. |
artifacts |
string |
no | Comma-separated NAME=PATH output artifacts; use CSV double quotes around entries containing commas. |
arguments |
string |
yes | Required comma-separated git command and literal argument tokens; never JSON. |
Returns Contract.ExecutionResult.
version #
Report the installed git CLI version.
| Argument | Type | Required | Description |
|---|---|---|---|
project |
string |
no | Working directory containing the source checkout; defaults to the current directory. Default: ".". |
run-dir |
string |
yes | Fresh directory for this invocation’s execution report and task logs; must not already exist. |
executable |
string |
no | Native CLI executable name or absolute path; defaults to this operation’s tool. |
timeout-ms |
integer |
no | Maximum task duration in milliseconds; defaults to 900000. Default: 900000. |
artifacts |
string |
no | Comma-separated NAME=PATH output artifacts; use CSV double quotes around entries containing commas. |
Returns Contract.ExecutionResult.
clone #
Clone a repository with optional shallow, partial and submodule checkout.
| Argument | Type | Required | Description |
|---|---|---|---|
project |
string |
no | Working directory containing the source checkout; defaults to the current directory. Default: ".". |
run-dir |
string |
yes | Fresh directory for this invocation’s execution report and task logs; must not already exist. |
executable |
string |
no | Native CLI executable name or absolute path; defaults to this operation’s tool. |
timeout-ms |
integer |
no | Maximum task duration in milliseconds; defaults to 900000. Default: 900000. |
artifacts |
string |
no | Comma-separated NAME=PATH output artifacts; use CSV double quotes around entries containing commas. |
branch |
string |
no | Branch or tag to check out. |
depth |
integer |
no | Positive shallow clone depth. |
filter |
string |
no | Partial clone filter, for example blob:none. |
recursive |
boolean |
no | Clone submodules recursively. |
single-branch |
boolean |
no | Fetch only one branch. |
url |
string |
yes | Repository URL or local source path. |
directory |
string |
no | Destination checkout directory; native Git chooses the default when omitted. |
extra-args |
string |
no | Comma-separated additional literal native tokens; no shell expansion. Empty entries are rejected; CSV quotes preserve literal commas. |
Returns Contract.ExecutionResult.
fetch #
Fetch selected refs and tags without merging them.
| Argument | Type | Required | Description |
|---|---|---|---|
project |
string |
no | Working directory containing the source checkout; defaults to the current directory. Default: ".". |
run-dir |
string |
yes | Fresh directory for this invocation’s execution report and task logs; must not already exist. |
executable |
string |
no | Native CLI executable name or absolute path; defaults to this operation’s tool. |
timeout-ms |
integer |
no | Maximum task duration in milliseconds; defaults to 900000. Default: 900000. |
artifacts |
string |
no | Comma-separated NAME=PATH output artifacts; use CSV double quotes around entries containing commas. |
prune |
boolean |
no | Remove stale remote-tracking refs. |
tags |
boolean |
no | Fetch all tags. |
depth |
integer |
no | Positive shallow fetch depth. |
remote |
string |
no | Remote name or URL. Default: "origin". |
refspecs |
string |
no | Refspecs to fetch; omit for the remote defaults. |
extra-args |
string |
no | Comma-separated additional literal native tokens; no shell expansion. Empty entries are rejected; CSV quotes preserve literal commas. |
Returns Contract.ExecutionResult.
checkout #
Check out a revision while retaining native dirty-worktree safety checks.
| Argument | Type | Required | Description |
|---|---|---|---|
project |
string |
no | Working directory containing the source checkout; defaults to the current directory. Default: ".". |
run-dir |
string |
yes | Fresh directory for this invocation’s execution report and task logs; must not already exist. |
executable |
string |
no | Native CLI executable name or absolute path; defaults to this operation’s tool. |
timeout-ms |
integer |
no | Maximum task duration in milliseconds; defaults to 900000. Default: 900000. |
artifacts |
string |
no | Comma-separated NAME=PATH output artifacts; use CSV double quotes around entries containing commas. |
detach |
boolean |
no | Check out a detached revision. |
ref |
string |
yes | Revision or existing branch to check out. |
extra-args |
string |
no | Comma-separated additional literal native tokens; no shell expansion. Empty entries are rejected; CSV quotes preserve literal commas. |
Returns Contract.ExecutionResult.
status #
Inspect checkout and index state with stable machine-readable output.
| Argument | Type | Required | Description |
|---|---|---|---|
project |
string |
no | Working directory containing the source checkout; defaults to the current directory. Default: ".". |
run-dir |
string |
yes | Fresh directory for this invocation’s execution report and task logs; must not already exist. |
executable |
string |
no | Native CLI executable name or absolute path; defaults to this operation’s tool. |
timeout-ms |
integer |
no | Maximum task duration in milliseconds; defaults to 900000. Default: 900000. |
artifacts |
string |
no | Comma-separated NAME=PATH output artifacts; use CSV double quotes around entries containing commas. |
porcelain |
string |
no | Stable machine-readable status format. Default: "v1". Allowed values: v1, v2. |
branch |
boolean |
no | Include branch information. |
paths |
string |
no | Optional pathspecs limiting status. |
extra-args |
string |
no | Comma-separated additional literal native tokens; no shell expansion. Empty entries are rejected; CSV quotes preserve literal commas. |
Returns Contract.ExecutionResult.
diff #
Compare source revisions or the working tree and optionally fail on differences.
| Argument | Type | Required | Description |
|---|---|---|---|
project |
string |
no | Working directory containing the source checkout; defaults to the current directory. Default: ".". |
run-dir |
string |
yes | Fresh directory for this invocation’s execution report and task logs; must not already exist. |
executable |
string |
no | Native CLI executable name or absolute path; defaults to this operation’s tool. |
timeout-ms |
integer |
no | Maximum task duration in milliseconds; defaults to 900000. Default: 900000. |
artifacts |
string |
no | Comma-separated NAME=PATH output artifacts; use CSV double quotes around entries containing commas. |
exit-code |
boolean |
no | Fail when differences exist. Default: true. |
cached |
boolean |
no | Compare the staged index. |
stat |
boolean |
no | Print a diff summary. |
revisions |
string |
no | Optional revisions and path tokens in native order. |
extra-args |
string |
no | Comma-separated additional literal native tokens; no shell expansion. Empty entries are rejected; CSV quotes preserve literal commas. |
Returns Contract.ExecutionResult.
log #
Read bounded commit history for release notes or change detection.
| Argument | Type | Required | Description |
|---|---|---|---|
project |
string |
no | Working directory containing the source checkout; defaults to the current directory. Default: ".". |
run-dir |
string |
yes | Fresh directory for this invocation’s execution report and task logs; must not already exist. |
executable |
string |
no | Native CLI executable name or absolute path; defaults to this operation’s tool. |
timeout-ms |
integer |
no | Maximum task duration in milliseconds; defaults to 900000. Default: 900000. |
artifacts |
string |
no | Comma-separated NAME=PATH output artifacts; use CSV double quotes around entries containing commas. |
max-count |
integer |
no | Maximum commits to print. Default: 20. |
format |
string |
no | Native Git log format. Default: "%H %s". |
revision |
string |
no | Optional revision range. |
extra-args |
string |
no | Comma-separated additional literal native tokens; no shell expansion. Empty entries are rejected; CSV quotes preserve literal commas. |
Returns Contract.ExecutionResult.
show #
Inspect a selected commit, tree or versioned file.
| Argument | Type | Required | Description |
|---|---|---|---|
project |
string |
no | Working directory containing the source checkout; defaults to the current directory. Default: ".". |
run-dir |
string |
yes | Fresh directory for this invocation’s execution report and task logs; must not already exist. |
executable |
string |
no | Native CLI executable name or absolute path; defaults to this operation’s tool. |
timeout-ms |
integer |
no | Maximum task duration in milliseconds; defaults to 900000. Default: 900000. |
artifacts |
string |
no | Comma-separated NAME=PATH output artifacts; use CSV double quotes around entries containing commas. |
format |
string |
no | Native commit formatting string. |
stat |
boolean |
no | Print changed-file statistics. |
object |
string |
no | Revision or object:path selector. Default: "HEAD". |
extra-args |
string |
no | Comma-separated additional literal native tokens; no shell expansion. Empty entries are rejected; CSV quotes preserve literal commas. |
Returns Contract.ExecutionResult.
rev-parse #
Resolve an exact commit or object identifier.
| Argument | Type | Required | Description |
|---|---|---|---|
project |
string |
no | Working directory containing the source checkout; defaults to the current directory. Default: ".". |
run-dir |
string |
yes | Fresh directory for this invocation’s execution report and task logs; must not already exist. |
executable |
string |
no | Native CLI executable name or absolute path; defaults to this operation’s tool. |
timeout-ms |
integer |
no | Maximum task duration in milliseconds; defaults to 900000. Default: 900000. |
artifacts |
string |
no | Comma-separated NAME=PATH output artifacts; use CSV double quotes around entries containing commas. |
verify |
boolean |
no | Require one valid revision. Default: true. |
revision |
string |
no | Revision expression to resolve. Default: "HEAD". |
extra-args |
string |
no | Comma-separated additional literal native tokens; no shell expansion. Empty entries are rejected; CSV quotes preserve literal commas. |
Returns Contract.ExecutionResult.
describe #
Derive a release identifier from Git tags and commit history.
| Argument | Type | Required | Description |
|---|---|---|---|
project |
string |
no | Working directory containing the source checkout; defaults to the current directory. Default: ".". |
run-dir |
string |
yes | Fresh directory for this invocation’s execution report and task logs; must not already exist. |
executable |
string |
no | Native CLI executable name or absolute path; defaults to this operation’s tool. |
timeout-ms |
integer |
no | Maximum task duration in milliseconds; defaults to 900000. Default: 900000. |
artifacts |
string |
no | Comma-separated NAME=PATH output artifacts; use CSV double quotes around entries containing commas. |
tags |
boolean |
no | Include lightweight tags. Default: true. |
always |
boolean |
no | Fall back to an abbreviated object name. Default: true. |
match |
string |
no | Tag name pattern. |
revision |
string |
no | Commit to describe. Default: "HEAD". |
extra-args |
string |
no | Comma-separated additional literal native tokens; no shell expansion. Empty entries are rejected; CSV quotes preserve literal commas. |
Returns Contract.ExecutionResult.
add #
Stage explicitly selected paths without implicitly staging all files.
| Argument | Type | Required | Description |
|---|---|---|---|
project |
string |
no | Working directory containing the source checkout; defaults to the current directory. Default: ".". |
run-dir |
string |
yes | Fresh directory for this invocation’s execution report and task logs; must not already exist. |
executable |
string |
no | Native CLI executable name or absolute path; defaults to this operation’s tool. |
timeout-ms |
integer |
no | Maximum task duration in milliseconds; defaults to 900000. Default: 900000. |
artifacts |
string |
no | Comma-separated NAME=PATH output artifacts; use CSV double quotes around entries containing commas. |
paths |
string |
yes | Required pathspecs to stage; directories are allowed. |
extra-args |
string |
no | Comma-separated additional literal native tokens; no shell expansion. Empty entries are rejected; CSV quotes preserve literal commas. |
Returns Contract.ExecutionResult.
commit #
Create a commit from staged changes using the inherited Git author identity.
| Argument | Type | Required | Description |
|---|---|---|---|
project |
string |
no | Working directory containing the source checkout; defaults to the current directory. Default: ".". |
run-dir |
string |
yes | Fresh directory for this invocation’s execution report and task logs; must not already exist. |
executable |
string |
no | Native CLI executable name or absolute path; defaults to this operation’s tool. |
timeout-ms |
integer |
no | Maximum task duration in milliseconds; defaults to 900000. Default: 900000. |
artifacts |
string |
no | Comma-separated NAME=PATH output artifacts; use CSV double quotes around entries containing commas. |
message |
string |
yes | Literal commit message; an editor is never opened. |
allow-empty |
boolean |
no | Allow a commit with no staged changes. |
signoff |
boolean |
no | Add a signoff trailer. |
extra-args |
string |
no | Comma-separated additional literal native tokens; no shell expansion. Empty entries are rejected; CSV quotes preserve literal commas. |
Returns Contract.ExecutionResult.
tag #
Create an explicitly named release tag without forcing replacement.
| Argument | Type | Required | Description |
|---|---|---|---|
project |
string |
no | Working directory containing the source checkout; defaults to the current directory. Default: ".". |
run-dir |
string |
yes | Fresh directory for this invocation’s execution report and task logs; must not already exist. |
executable |
string |
no | Native CLI executable name or absolute path; defaults to this operation’s tool. |
timeout-ms |
integer |
no | Maximum task duration in milliseconds; defaults to 900000. Default: 900000. |
artifacts |
string |
no | Comma-separated NAME=PATH output artifacts; use CSV double quotes around entries containing commas. |
message |
string |
no | Annotated tag message; omit for a lightweight tag. |
sign |
boolean |
no | Cryptographically sign the tag using configured signing credentials. |
name |
string |
yes | New tag name. |
target |
string |
no | Commit or object to tag. Default: "HEAD". |
extra-args |
string |
no | Comma-separated additional literal native tokens; no shell expansion. Empty entries are rejected; CSV quotes preserve literal commas. |
Returns Contract.ExecutionResult.
push #
Push selected refs; force updates and tag publication are opt-in.
| Argument | Type | Required | Description |
|---|---|---|---|
project |
string |
no | Working directory containing the source checkout; defaults to the current directory. Default: ".". |
run-dir |
string |
yes | Fresh directory for this invocation’s execution report and task logs; must not already exist. |
executable |
string |
no | Native CLI executable name or absolute path; defaults to this operation’s tool. |
timeout-ms |
integer |
no | Maximum task duration in milliseconds; defaults to 900000. Default: 900000. |
artifacts |
string |
no | Comma-separated NAME=PATH output artifacts; use CSV double quotes around entries containing commas. |
tags |
boolean |
no | Push all local tags. |
atomic |
boolean |
no | Require atomic remote ref updates. |
set-upstream |
boolean |
no | Set upstream tracking for pushed branches. |
force-with-lease |
boolean |
no | Explicitly request guarded forced ref updates; omitted by default. |
remote |
string |
no | Remote name or URL. Default: "origin". |
refspecs |
string |
no | Optional refspecs in native order. |
extra-args |
string |
no | Comma-separated additional literal native tokens; no shell expansion. Empty entries are rejected; CSV quotes preserve literal commas. |
Returns Contract.ExecutionResult.
pull #
Update the checkout, requiring a fast-forward by default.
| Argument | Type | Required | Description |
|---|---|---|---|
project |
string |
no | Working directory containing the source checkout; defaults to the current directory. Default: ".". |
run-dir |
string |
yes | Fresh directory for this invocation’s execution report and task logs; must not already exist. |
executable |
string |
no | Native CLI executable name or absolute path; defaults to this operation’s tool. |
timeout-ms |
integer |
no | Maximum task duration in milliseconds; defaults to 900000. Default: 900000. |
artifacts |
string |
no | Comma-separated NAME=PATH output artifacts; use CSV double quotes around entries containing commas. |
ff-only |
boolean |
no | Require a fast-forward update. Default: true. |
remote |
string |
no | Remote name or URL. Default: "origin". |
branch |
string |
no | Optional branch to pull. |
extra-args |
string |
no | Comma-separated additional literal native tokens; no shell expansion. Empty entries are rejected; CSV quotes preserve literal commas. |
Returns Contract.ExecutionResult.
submodule-update #
Initialize and update submodules at their committed revisions.
| Argument | Type | Required | Description |
|---|---|---|---|
project |
string |
no | Working directory containing the source checkout; defaults to the current directory. Default: ".". |
run-dir |
string |
yes | Fresh directory for this invocation’s execution report and task logs; must not already exist. |
executable |
string |
no | Native CLI executable name or absolute path; defaults to this operation’s tool. |
timeout-ms |
integer |
no | Maximum task duration in milliseconds; defaults to 900000. Default: 900000. |
artifacts |
string |
no | Comma-separated NAME=PATH output artifacts; use CSV double quotes around entries containing commas. |
init |
boolean |
no | Initialize selected submodules. Default: true. |
recursive |
boolean |
no | Update nested submodules. Default: true. |
depth |
integer |
no | Positive shallow submodule depth. |
paths |
string |
no | Optional submodule pathspecs. |
extra-args |
string |
no | Comma-separated additional literal native tokens; no shell expansion. Empty entries are rejected; CSV quotes preserve literal commas. |
Returns Contract.ExecutionResult.
ls-remote #
Inspect remote refs without checking out or modifying repository contents.
| Argument | Type | Required | Description |
|---|---|---|---|
project |
string |
no | Working directory containing the source checkout; defaults to the current directory. Default: ".". |
run-dir |
string |
yes | Fresh directory for this invocation’s execution report and task logs; must not already exist. |
executable |
string |
no | Native CLI executable name or absolute path; defaults to this operation’s tool. |
timeout-ms |
integer |
no | Maximum task duration in milliseconds; defaults to 900000. Default: 900000. |
artifacts |
string |
no | Comma-separated NAME=PATH output artifacts; use CSV double quotes around entries containing commas. |
tags |
boolean |
no | List tags only. |
heads |
boolean |
no | List branch heads only. |
remote |
string |
no | Remote URL or configured name. Default: "origin". |
patterns |
string |
no | Optional ref-name patterns. |
extra-args |
string |
no | Comma-separated additional literal native tokens; no shell expansion. Empty entries are rejected; CSV quotes preserve literal commas. |
Returns Contract.ExecutionResult.
archive #
Create a source release archive from a selected Git tree.
| Argument | Type | Required | Description |
|---|---|---|---|
project |
string |
no | Working directory containing the source checkout; defaults to the current directory. Default: ".". |
run-dir |
string |
yes | Fresh directory for this invocation’s execution report and task logs; must not already exist. |
executable |
string |
no | Native CLI executable name or absolute path; defaults to this operation’s tool. |
timeout-ms |
integer |
no | Maximum task duration in milliseconds; defaults to 900000. Default: 900000. |
artifacts |
string |
no | Comma-separated NAME=PATH output artifacts; use CSV double quotes around entries containing commas. |
format |
string |
no | Archive format. Default: "tar". Allowed values: tar, zip. |
output |
string |
yes | Destination archive file. |
prefix |
string |
no | Prefix for paths inside the archive. |
tree |
string |
no | Tree or commit to archive. Default: "HEAD". |
paths |
string |
no | Optional paths to include. |
extra-args |
string |
no | Comma-separated additional literal native tokens; no shell expansion. Empty entries are rejected; CSV quotes preserve literal commas. |
Returns Contract.ExecutionResult.
config-get #
Read one configured Git value without modifying configuration.
| Argument | Type | Required | Description |
|---|---|---|---|
project |
string |
no | Working directory containing the source checkout; defaults to the current directory. Default: ".". |
run-dir |
string |
yes | Fresh directory for this invocation’s execution report and task logs; must not already exist. |
executable |
string |
no | Native CLI executable name or absolute path; defaults to this operation’s tool. |
timeout-ms |
integer |
no | Maximum task duration in milliseconds; defaults to 900000. Default: 900000. |
artifacts |
string |
no | Comma-separated NAME=PATH output artifacts; use CSV double quotes around entries containing commas. |
key |
string |
yes | Git configuration key to query. |
extra-args |
string |
no | Comma-separated additional literal native tokens; no shell expansion. Empty entries are rejected; CSV quotes preserve literal commas. |
Returns Contract.ExecutionResult.
remote-get-url #
Read the configured repository remote URL.
| Argument | Type | Required | Description |
|---|---|---|---|
project |
string |
no | Working directory containing the source checkout; defaults to the current directory. Default: ".". |
run-dir |
string |
yes | Fresh directory for this invocation’s execution report and task logs; must not already exist. |
executable |
string |
no | Native CLI executable name or absolute path; defaults to this operation’s tool. |
timeout-ms |
integer |
no | Maximum task duration in milliseconds; defaults to 900000. Default: 900000. |
artifacts |
string |
no | Comma-separated NAME=PATH output artifacts; use CSV double quotes around entries containing commas. |
remote |
string |
no | Remote name to inspect. Default: "origin". |
extra-args |
string |
no | Comma-separated additional literal native tokens; no shell expansion. Empty entries are rejected; CSV quotes preserve literal commas. |
Returns Contract.ExecutionResult.