Foundry.GitCommitBuilder¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`new` (vcs, parent, context_lines)
	`commit` ()
	`dup_author_email` ()
	`dup_author_name` ()
	`dup_message` ()
	`dup_signing_format` ()
	`dup_signing_key` ()
	`dup_when` ()
	`get_can_commit` ()
	`is_untracked` (file)
	`list_staged` ()
	`list_unstaged` ()
	`list_untracked` ()
	`load_staged_delta` (file)
	`load_unstaged_delta` (file)
	`load_untracked_delta` (file)
	`new_similar` ()
	`set_author_email` (author_email)
	`set_author_name` (author_name)
	`set_message` (message)
	`set_signing_format` (signing_format)
	`set_signing_key` (signing_key)
	`set_when` (when)
	`stage_file` (file)
	`stage_hunks` (file, hunks)
	`stage_lines` (file, lines)
	`unstage_file` (file)
	`unstage_hunks` (file, hunks)
	`unstage_lines` (file, lines)

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

Name	Type	Flags
`author-email`	`str`	r/w/en
`author-name`	`str`	r/w/en
`can-commit`	`bool`	r
`message`	`str`	r/w/en
`signing-format`	`str`	r/w/en
`signing-key`	`str`	r/w/en
`staged`	`Gio.ListModel`	r
`unstaged`	`Gio.ListModel`	r
`untracked`	`Gio.ListModel`	r
`when`	`GLib.DateTime`	r/w/en

Signals¶

Inherited:: GObject.Object (1)

Fields¶

Inherited:: GObject.Object (1)

Class Details¶

class Foundry.GitCommitBuilder(**kwargs)¶

Bases:: GObject.Object
Abstract:: No
Structure:: Foundry.GitCommitBuilderClass

classmethod new(vcs, parent, context_lines)¶

Parameters:

vcs (Foundry.GitVcs) – a [class`Foundry`.GitVcs]
parent (Foundry.GitCommit or None) – a [class`Foundry`.GitCommit]
context_lines (int) – the number of context lines to use for diffs or 0 for default

Returns:

a [class`Dex`.Future] that resolves to a [class`Foundry`.GitCommitBuilder].

Return type:

Dex.Future

Creates a new builder using parent as the parent commit.

If parent is None, then the last commit on the current branch will be used as the parent.

The context_lines parameter controls how many lines of context are included around each change in the diff. The default is 3 lines.

New in version 1.1.

commit()¶

Returns:: a [class`Dex`.Future] that resolves to a [class`Foundry`.GitCommit] or rejects with error
Return type:: Dex.Future

Creates a commit using the fields from the builder.

New in version 1.1.

dup_author_email()¶

Returns:: the author email, or None if not set. The caller should free the returned string with GLib.free() when done.
Return type:: str or None

Gets the author email address that will be used for the commit.

New in version 1.1.

dup_author_name()¶

Returns:: the author name, or None if not set. The caller should free the returned string with GLib.free() when done.
Return type:: str or None

Gets the author name that will be used for the commit.

New in version 1.1.

dup_message()¶

Returns:: the commit message, or None if not set. The caller should free the returned string with GLib.free() when done.
Return type:: str or None

Gets the commit message that will be used for the commit.

New in version 1.1.

dup_signing_format()¶

Returns:: the signing format (e.g. “gpg” or “ssh”), or None if not set. The caller should free the returned string with GLib.free() when done.
Return type:: str or None

Gets the signing format that will be used for signing the commit.

New in version 1.1.

dup_signing_key()¶

Returns:: the signing key identifier, or None if not set. The caller should free the returned string with GLib.free() when done.
Return type:: str or None

Gets the signing key identifier that will be used for signing the commit.

New in version 1.1.

dup_when()¶

Returns:: a [struct`GLib`.DateTime] representing the commit timestamp, or None if not set. The caller should free the returned object with GLib.DateTime.unref() when done.
Return type:: GLib.DateTime or None

Gets the timestamp that will be used for the commit.

New in version 1.1.

get_can_commit()¶

Returns:: True if a commit can be created, False otherwise
Return type:: bool

Checks whether the builder has sufficient information to create a commit.

Returns True if both a non-empty commit message and at least one staged file are present. Returns False otherwise.

New in version 1.1.

is_untracked(file)¶

Parameters:: file (Gio.File) – a [iface`Gio`.File] to check
Returns:: True if file was untracked when the builder was created, False otherwise
Return type:: bool

Checks whether file was untracked when the commit builder was created.

This method checks if the file was in the untracked files list at the time the commit builder was initialized. Note that this reflects the state when the builder was created, not the current git status.

New in version 1.1.

list_staged()¶

Returns:: a [iface`Gio`.ListModel] of [class`Foundry`.GitStatusEntry] objects representing staged files
Return type:: Gio.ListModel

Gets a list model containing all files that are currently staged for commit.

The list model contains [class`Foundry`.GitStatusEntry] objects representing files in the working tree that have been staged. The list is updated automatically as files are staged or unstaged.

New in version 1.1.

list_unstaged()¶

Returns:: a [iface`Gio`.ListModel] of [class`Foundry`.GitStatusEntry] objects representing files with unstaged changes
Return type:: Gio.ListModel

Gets a list model containing all files that have unstaged changes.

The list model contains [class`Foundry`.GitStatusEntry] objects representing files in the working tree that have been modified but not staged. The list is updated automatically as files are staged or unstaged.

New in version 1.1.

list_untracked()¶

Returns:: a [iface`Gio`.ListModel] of [class`Foundry`.GitStatusEntry] objects representing untracked files
Return type:: Gio.ListModel

Gets a list model containing all untracked files in the working tree.

The list model contains [class`Foundry`.GitStatusEntry] objects representing files in the working tree that are not tracked by git. The list is updated automatically as files are staged or untracked files are added.

New in version 1.1.

load_staged_delta(file)¶

Parameters:: file (Gio.File) – a [iface`Gio`.File] in the working tree
Returns:: a [class`Dex`.Future] that resolves to a [class`Foundry`.GitDelta] or rejects with error.
Return type:: Dex.Future

Loads the delta for file comparing the index against the parent commit. This delta represents staged changes and can be used to toggle individual lines on/off for staging in the background.

New in version 1.1.

load_unstaged_delta(file)¶

Parameters:: file (Gio.File) – a [iface`Gio`.File] in the working tree
Returns:: a [class`Dex`.Future] that resolves to a [class`Foundry`.GitDelta] or rejects with error.
Return type:: Dex.Future

Loads the delta for file comparing the working directory against the index. This delta represents unstaged changes and can be used to toggle individual lines on/off for staging in the background.

New in version 1.1.

load_untracked_delta(file)¶

Parameters:: file (Gio.File) – a [iface`Gio`.File] in the working tree
Returns:: a [class`Dex`.Future] that resolves to a [class`Foundry`.GitDelta] or rejects with error.
Return type:: Dex.Future

Loads the delta for an untracked file. This creates a synthetic delta that represents adding the entire file, allowing the same API semantics for new files as for modified files. The delta can be used to toggle individual lines on/off for staging in the background.

The file must be untracked (not in git’s index) when the commit builder was created. Since untracked files are new files, the delta will contain a single hunk with all lines marked as additions.

New in version 1.1.

new_similar()¶

Returns:: a [class`Dex`.Future] that resolves to a [class`Foundry`.GitCommitBuilder].
Return type:: Dex.Future

Creates a new builder similar to self, copying all string and GLib.DateTime properties from the existing builder.

The new builder will use the same VCS instance, parent commit (or HEAD if no parent was set), context lines, author name, author email, signing key, signing format, and timestamp as self.

New in version 1.1.

set_author_email(author_email)¶

Parameters:: author_email (str or None) – the author email to use, or None to unset

Sets the author email address that will be used for the commit.

If set to None or not set, the value from git config “user.email” will be used when creating the commit.

New in version 1.1.

set_author_name(author_name)¶

Parameters:: author_name (str or None) – the author name to use, or None to unset

Sets the author name that will be used for the commit.

If set to None or not set, the value from git config “user.name” will be used when creating the commit.

New in version 1.1.

set_message(message)¶

Parameters:: message (str or None) – the commit message to use, or None to unset

Sets the commit message that will be used for the commit.

This must be set to a non-empty string before a commit can be created. Setting this will automatically update the [property`Foundry`.GitCommitBuilder:can-commit] property.

New in version 1.1.

set_signing_format(signing_format)¶

Parameters:: signing_format (str or None) – the signing format to use (e.g. “gpg” or “ssh”), or None for default

Sets the signing format that will be used for signing the commit.

Common values are “gpg” for GPG signatures or “ssh” for SSH signatures. If set to None, defaults to “gpg”.

New in version 1.1.

set_signing_key(signing_key)¶

Parameters:: signing_key (str or None) – the signing key identifier to use, or None to disable signing

Sets the signing key identifier that will be used for signing the commit.

If set, the commit will be signed using the specified key and the signing format. If set to None, the commit will not be signed.

New in version 1.1.

set_when(when)¶

Parameters:: when (GLib.DateTime or None) – the timestamp to use for the commit, or None to use current time

Sets the timestamp that will be used for the commit.

If set to None or not set, the current time will be used when creating the commit. The builder takes ownership of when.

New in version 1.1.

stage_file(file)¶

Parameters:: file (Gio.File) – a [iface`Gio`.File] in the working tree
Returns:: a [class`Dex`.Future] that resolves to any value or rejects with error
Return type:: Dex.Future

Stages the file using the version from the stored diff/delta. This stages the fully applied version (all changes from the delta).

New in version 1.1.

stage_hunks(file, hunks)¶

Parameters:

file (Gio.File) – a [iface`Gio`.File] in the working tree
hunks (Gio.ListModel) – a [iface`Gio`.ListModel] of [class`Foundry`.GitDiffHunk]

Returns:

a [class`Dex`.Future] that resolves to any value or rejects with error

Return type:

Dex.Future

Stages the selected hunks from the file.

New in version 1.1.

stage_lines(file, lines)¶

Parameters:

file (Gio.File) – a [iface`Gio`.File] in the working tree
lines (Gio.ListModel) – a [iface`Gio`.ListModel] of [class`Foundry`.GitDiffLine]

Returns:

a [class`Dex`.Future] that resolves to any value or rejects with error

Return type:

Dex.Future

Stages the selected lines from the file.

New in version 1.1.

unstage_file(file)¶

Parameters:: file (Gio.File) – a [iface`Gio`.File] in the working tree
Returns:: a [class`Dex`.Future] that resolves to any value or rejects with error
Return type:: Dex.Future

Unstages the file using the version from the stored diff/delta. This restores the file to the fully unapplied version (HEAD version).

New in version 1.1.

unstage_hunks(file, hunks)¶

Parameters:

file (Gio.File) – a [iface`Gio`.File] in the working tree
hunks (Gio.ListModel) – a [iface`Gio`.ListModel] of [class`Foundry`.GitDiffHunk]

Returns:

a [class`Dex`.Future] that resolves to any value or rejects with error

Return type:

Dex.Future

Unstages the selected hunks from the file.

New in version 1.1.

unstage_lines(file, lines)¶

Parameters:

file (Gio.File) – a [iface`Gio`.File] in the working tree
lines (Gio.ListModel) – a [iface`Gio`.ListModel] of [class`Foundry`.GitDiffLine]

Returns:

a [class`Dex`.Future] that resolves to any value or rejects with error

Return type:

Dex.Future

Unstages the selected lines from the file.

New in version 1.1.

Property Details¶

Foundry.GitCommitBuilder.props.author_email¶

Name:: author-email
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The email address of the commit author.

If not set, the value from git config “user.email” will be used when creating the commit.

Foundry.GitCommitBuilder.props.author_name¶

Name:: author-name
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The name of the commit author.

If not set, the value from git config “user.name” will be used when creating the commit.

Foundry.GitCommitBuilder.props.can_commit¶

Name:: can-commit
Type:: bool
Default Value:: False
Flags:: READABLE

Whether the builder has sufficient information to create a commit.

This property is True when both a non-empty commit message and at least one staged file are present. It is read-only and will be updated automatically as files are staged or unstaged and as the message changes.

Foundry.GitCommitBuilder.props.message¶

Name:: message
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The commit message.

This must be set to a non-empty string before a commit can be created.

Foundry.GitCommitBuilder.props.signing_format¶

Name:: signing-format
Type:: str
Default Value:: 'gpg'
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The format to use for signing commits.

Common values are “gpg” for GPG signatures or “ssh” for SSH signatures. Defaults to “gpg” if not set.

Foundry.GitCommitBuilder.props.signing_key¶

Name:: signing-key
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The key identifier to use for signing the commit.

If set, the commit will be signed using the specified key and the signing format. If not set, the commit will not be signed.

Foundry.GitCommitBuilder.props.staged¶

Name:: staged
Type:: Gio.ListModel
Default Value:: None
Flags:: READABLE

A list model containing all files that are currently staged for commit.

The list model contains [class`Foundry`.GitStatusEntry] objects representing files in the working tree that have been staged. The list is updated automatically as files are staged or unstaged.

Foundry.GitCommitBuilder.props.unstaged¶

Name:: unstaged
Type:: Gio.ListModel
Default Value:: None
Flags:: READABLE

A list model containing all files that have unstaged changes.

The list model contains [class`Foundry`.GitStatusEntry] objects representing files in the working tree that have been modified but not staged. The list is updated automatically as files are staged or unstaged.

Foundry.GitCommitBuilder.props.untracked¶

Name:: untracked
Type:: Gio.ListModel
Default Value:: None
Flags:: READABLE

A list model containing all untracked files in the working tree.

The list model contains [class`Foundry`.GitStatusEntry] objects representing files in the working tree that are not tracked by git. The list is updated automatically as files are staged or untracked files are added.

Foundry.GitCommitBuilder.props.when¶

Name:: when
Type:: GLib.DateTime
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The timestamp for the commit.

If not set, the current time will be used when creating the commit.