git-custom-cli 2.4.0

Fast, keyboard-driven terminal UI for dated Git commits
git-custom-cli-2.4.0 is not a library.

git-custom-cli (gct)

gct is a keyboard-driven terminal UI for Git. Its original job, and still the default, is making commits with a custom date and time, a branch to push to, and a multiline message. It now also has 21 modes for everyday Git work, history, fixing mistakes and releases (see Modes), with confirmations and backups for risky actions (see Safety model). You fill in the fields from a menu, review a summary, and then gct stages everything, creates the commit, and optionally pushes it to origin. It is written in Rust on top of crossterm, and it runs on Windows, macOS and Linux.

Features

  • Menu-driven commit flow with a "fields ready" counter (date, time, branch, message).
  • Left / Right on the menu rows change the date (one day), the time (one minute), the branch (your local branches), the commit mode and the active account without opening an editor.
  • Keyboard date (YYYY-MM-DD) and time (HH:MM:SS) masks that reject invalid values, with n, y, -, + and r shortcuts.
  • Notepad-style multiline message editor with a clickable Save & go back button (word jumps, blinking bar cursor), a single-line branch editor, and an external editor option.
  • Header with the current branch, the Git user name and a working-tree label that opens the full git status --short list.
  • Normal commit, amend mode, and dry run (preview only).
  • Commit date applied to both author and committer date.
  • Optional push to origin after the commit, with --force-with-lease when amending.
  • Push only (menu row and --push-only flag) to push existing local commits, for example to retry a failed push.
  • A failed stage, commit or push shows the error in the menu instead of closing gct.
  • A spinner while staging, committing and pushing.
  • Last date, branch and message are remembered for the next run.
  • A small mascot in the header that turns toward the mouse pointer.
  • Optional theme and keys settings in the config file (see Theme and keys).
  • Saved Git accounts (label, name, email, GitHub username) that you can switch between. See Accounts.
  • Multi-mode controller: stage, branch, sync, stash, log, undo, conflicts, tags and more, opened with gct --hub or gct --mode <name>. See Modes.

Requirements

  • Rust and Cargo, to install or build from source. The crate uses edition 2021.
  • Git available on PATH.
  • An interactive terminal for the TUI. gct refuses to open the TUI when stdin or stdout is not a terminal. The flag mode works without one.
  • Run it from inside a Git repository, except for the modes marked as working outside one in Modes.
  • Git 2.30 or newer for the git modes (stage, branch, sync, and so on). The commit, account and settings modes do not need it.

[!IMPORTANT] gct must be started directly in a shell. Piping its output or running it from a script without a terminal makes it exit with gct needs an interactive terminal; run it directly in a shell. From scripts and agents, use the flags instead (see Commit without the TUI).

Installation

Install the published crate:

cargo install git-custom-cli

The package is named git-custom-cli, but the installed binary is named gct.

To build from source instead:

git clone <repository-url>
cd git-custom-cli

cargo build --release

The optimized binary is written to target/release/gct (target\release\gct.exe on Windows).

To check which version you have, run gct --version.

Quick start

  1. Open a terminal in a Git repository that has changes to commit.
  2. Run gct.
  3. Set the date, time, branch and message from the menu. Use Enter on each row.
  4. Choose Finalize & commit.
  5. Confirm the summary, then answer the push question.

To save several Git accounts and switch between them, run gct --account. See Accounts.

To explore the other modes, run gct --hub. It lists them by group, and Tab switches between Basic and All modes.

Commit without the TUI

Pass any of these flags and gct stages everything and commits straight away, with no menu. Add --push to also push:

gct -d 2026-05-05 -t 15:45:15 -b main -m "feat: add auth" -ml "- integrate login - integrate register" --push

Flag Meaning Default
-d Date YYYY-MM-DD (YYYY:MM:DD also works) today
-t Time HH:MM:SS now
-b Branch to push to current branch
-m One-line message (required)
-ml Description: items separated by -, each becomes a bullet none
--push Push to origin/<branch> after committing local commit only
--push-only Push existing local commits to origin/<branch> without committing (needs a checked-out branch; verifies the active account's login like --push) off
--amend Amend the last commit instead of creating a new one. With --push, the push uses --force-with-lease off
--dry-run Print the commands that would run and change nothing off

--push-only cannot be combined with --push, --amend, --dry-run, -m, -ml, -d or -t. It can be combined with -b.

To push commits you already made, without creating a new one:

gct --push-only -b main

It prints Done. push origin/main on success. This mode never uses --force-with-lease.

In flag mode, an error is printed as Error: ... and gct exits with code 1.

The example above produces this message:

feat: add auth

- integrate login
- integrate register

Separate -ml items with - (space, dash, space) or put one item per line. Text inside an item can then mention flags such as -d or --agent. The short form -ml "-one -two" also works, but it starts a new item at every dash after a space (never at --).

Run gct --agent to print this format for an AI agent, so it can write gct commands for you. The TUI modes need a terminal and are not meant for scripts.

Modes

gct has 21 modes. Plain gct opens your default mode, which is commit unless you change it in Settings (an unknown name in the config falls back to commit).

Command What it does
gct Opens the default mode (setting default_mode, default commit)
gct --hub Opens the hub: modes grouped by Start, Everyday, History, Fix, Release and Setup. Enter or a click opens one, and you return to the hub when it closes. Tab switches between Basic modes and All modes (the pro experience level starts on All). Esc / q leaves
gct --settings Opens the settings screen (see Config reference)
gct --mode <name> Opens any mode by name or alias, case-insensitive. A wrong name prints the list of valid modes

Mode flags (--hub, --settings, --mode, --commit, --stage, --status, --sync, --log, --stash, --undo, --tag) cannot be combined with each other or with the commit flags (-d -t -b -m -ml --push --push-only --amend --dry-run). Every mode needs an interactive terminal. --account also opens a mode (Accounts).

--branch is not a mode shortcut, because -b/--branch already means the branch to push to. Use gct --mode branch.

Modes marked "no" in the last column need a Git repository. Outside one they show a "Not a git repository" notice and point you to Start mode.

Mode Alias Group Level What it does Flag Works outside a repo
commit Everyday Basic Dated commits: date, time, branch, message, push --commit yes
status Everyday Basic Where you are: branch, upstream and changes --status no
stage Everyday Basic Pick files and hunks for the next commit; view diffs --stage no
branch Everyday Basic Create, switch, rename, merge and delete branches none (use --mode branch) no
sync Everyday Basic Fetch, pull and push; manage remotes --sync no
stash Everyday Advanced Put work aside and bring it back later --stash no
log History Basic Browse and search commit history --log no
files History Advanced Browse files and see who changed each line none no
compare History Advanced Compare two branches or commits none no
undo rescue Fix Basic Undo recent actions and recover lost work --undo no
conflicts resolve Fix Basic Resolve merge conflicts file by file none no
timetravel Fix Advanced Change the dates of existing commits (no rebase) none no
tag Release Advanced Mark releases: list, create, push and delete tags --tag no
account Setup Basic Saved GitHub accounts and the active identity --account yes
settings Setup Basic Default mode, experience, safety and theme --settings yes
config Setup Advanced Your name, email and common git settings none no
ignore Setup Advanced Keep files out of git with .gitignore none no
commands Setup Advanced Every git command gct ran in this session none yes
hub Setup Basic Launcher for every mode --hub yes
start Start Basic Create a new repository or clone one none yes
guide Start Basic What to do next, explained step by step none yes

[!NOTE] Modes that need a repository check your Git version once per session. Some actions need Git 2.30 or newer (for example --force-if-includes in a force push). An older Git shows a notice instead of blocking you. The commit, account and settings modes do not need Git 2.30.

List screens share these keys: Up / Down or w / s to move, PgUp / PgDn, Home / End, Enter or a click to open the selected row, and Esc / q to go back. A mode's extra keys show in its footer line, and the tables below list them.

Everyday

commit is the original dated-commit menu, described under Usage and Commit modes. Pushing an amended commit uses --force-with-lease.

status is a read-only dashboard of the branch, its upstream and the changed files. Key: r refresh.

stage lists changed files. Open one to see its diff and to stage, unstage or discard single hunks.

Key Action
a / u Stage / unstage
x Discard
A / U Stage all / unstage all (Shift)
i Ignore
c Commit
d Diff
r / m Refresh / menu

In a diff view, ] and [ jump between hunks, / searches and n / N go to the next match. Discarding changes always asks for confirmation, whatever your settings.

branch keys: n new, R rename (Shift), d delete, u upstream, m merge, c compare, p prune, v local / remote list, r refresh. Deleting a branch saves a backup ref first.

sync rows and keys: Fetch (f), Pull (l), Push (p), Push and set upstream (u, shown only when the branch has no upstream), Force push with lease (x, hidden at the beginner level) and Remotes (m). The Remotes screen has a add, n rename, u set URL, d remove. Sync uses the default_remote setting. Force pushes use --force-with-lease (never plain --force) and are refused on protected branches.

stash keys: n new, a apply, p pop, d drop, b branch from a stash, c clear all, r refresh. Dropping or clearing saves a backup ref first.

History

log browses history with a graph and search. Keys: v view, y copy hash, c checkout, r revert, p cherry-pick, t tag, b branch, d diff vs HEAD, C contributors (Shift), f filters, g graph, a all branches, 1 first-parent, n more. In a merge commit's view, m shows the first-parent diff.

files lists tracked files (f changes the filter). Open a file for its history, a blame view, or the history of a line range. In blame: b blame before this change, n / p next / previous window. Nothing here changes the repository.

compare compares two branches or commits. Keys: t two or three dots, c commits, x swap A and B, r refresh, m menu. Nothing here changes the repository.

Fix

undo (alias rescue) opens a menu: undo my last git action, a guided "I made a mistake" fix, a reflog browser, restore from a gct backup, and manage gct backups. The guided fix covers a commit on the wrong branch, undoing a commit but keeping the changes, amending, a detached HEAD, a merge or pull that went wrong, lost commits, and a pushed secret. Every history-moving action saves a backup ref first and names it in the result. Reflog keys: v view, k reset --keep, h reset --hard, b new branch, r refresh. Backup keys: v view, x restore, b as branch, d delete, p prune backups older than 30 days. See Backup refs.

conflicts (alias resolve) finishes or cancels a merge, rebase, cherry-pick, revert or git am that is in progress. Per file you can keep one side (labels follow the operation, because "ours" and "theirs" swap in a rebase), edit in $VISUAL / $EDITOR, mark it resolved, view the diff or run the merge tool. For the whole operation you can continue, skip or abort. Abort saves a backup ref first.

timetravel changes the author and committer dates of existing commits on the current branch without a rebase: each commit is rewritten with its tree unchanged and the branch moves in one compare-and-swap update. It shows a preview, saves a backup ref, handles at most 500 commits per run, and never pushes. When choosing a range, n picks the last N commits. If the commits were already pushed, it tells you that you will need a force-with-lease push (from Sync). On a protected branch, rewriting published commits makes you type the branch name.

Release

tag keys: n new annotated, l new lightweight, d delete local, c changelog, r refresh. With a remote there are also p push, P push all (Shift) and D delete remote (Shift). Deleting a tag asks first and saves a backup ref.

Setup

account is gct --account, described under Accounts.

settings edits the values in Config reference. Footer: Up / Down move, Left / Right change, Enter edit, Del clear accent, Esc / q save and back. Changes are saved when you leave, and theme changes apply live.

config (Git config) has a menu for identity (name and email), default branch name, pull strategy, line endings and aliases, plus a read-only look at your hooks. Writes to global config show the exact command and ask first.

ignore edits the repository's .gitignore: ignore untracked files, add templates, stop tracking a file, explain why a path is ignored, and a plain-English git glossary.

commands lists the git commands gct ran in this session. Enter shows one in full. See Show git commands.

hub is the launcher described above.

Start

start gets you from nothing to a pushed first commit, and it also works outside a repository. Outside one it offers to create a repository here, create one in a new folder, or clone a URL (a non-empty target folder is refused, and creating a repository in your home folder or a drive root asks first). Inside a repository it shows a checklist: repository exists, identity set, .gitignore present, first commit made, remote added, branch pushed. Enter on an unchecked row runs that step. The first-commit step lists untracked files first and warns about common junk such as node_modules/ or .env, offering to open Ignore.

guide suggests next steps for the current state of the repository, most important first, and opens the mode that does each one. Outside a repository it offers to open Start. Key: r refresh.

Safety model

Every mode asks policy.rs how much confirmation an action needs, so the same kind of action is treated the same way everywhere.

Tier Examples When it asks
Plain Fetch, viewing, switching Never
Confirm (yes/no, default Yes) Creating a commit, deleting a merged branch Unless confirm_destructive is off
Danger (red warning, default No) Reset --hard, deleting an unmerged branch, dropping a stash, deleting a tag, aborting a merge or rebase, rewriting commits that are not published Unless confirm_destructive is off
Always asks Discarding changes (tracked or untracked), rewriting commits that are already published, force-pushing a branch that is not protected Always, whatever the settings
Typed confirmation Rewriting published commits on a protected branch: you must type the branch name Always
Refused Force-pushing a protected branch. gct shows a notice and does nothing; run git by hand if you really must Never allowed

Protected branches come from the protected_branches setting (default main and master). An entry ending in * matches a prefix, for example release/*; any other entry must match the whole name. Turning off confirm_destructive never weakens the last three rows or the "Always asks" row.

Backup refs

Before it resets hard, deletes a branch or tag, drops or clears stashes, aborts a merge or rebase, rewrites commit dates or restores a backup, gct saves a plain git ref named refs/gct/backup/<YYYYMMDD-HHMMSS>-<label>. It does this even when confirm_destructive is off. The ref keeps the commits alive, and the result screen names it.

To list and restore backups, open Undo mode (gct --undo) and choose "Restore from a gct backup" or "Manage gct backups". You can view a backup's commits, restore it (reset the current branch to it, after backing up the current HEAD), restore it as a new branch, delete it, or prune backups older than 30 days. By hand, git for-each-ref refs/gct/backup/ lists them and git reset --hard <refname> restores one.

No raw force push

gct never runs git push --force. Force pushes use --force-with-lease with the value gct last saw on the remote, plus --force-if-includes, so the push is refused if someone else pushed in the meantime. Pushing an amended commit from commit mode also uses --force-with-lease.

Show git commands and the Commands log

Turn on show_commands in Settings and the spinner shows the exact $ git ... command while it runs. Confirmation screens show the command that will run. Open gct --mode commands to see every git command gct ran in this session, newest first, with its exit code and duration. The log keeps the last 200 commands in memory only and is gone when gct exits. Secrets are masked: passwords in URLs, GitHub tokens and http.extraheader values show as ***.

Experience levels

Set experience in Settings. An unknown value acts as normal.

Level What changes
beginner Some modes add plain-language explanations, Guide adds the reason for its top suggestion, and Sync hides the force push row. Switching to beginner turns confirm_destructive and show_commands on once; you can turn them off again afterwards
normal The default
pro The hub opens on All modes instead of Basic modes

Hooks

gct never installs or edits git hooks. Git config mode only shows the hooks that already exist.

Setup

Git identity

The main menu header shows the GitHub tag with the name gct reads from git config --get user.name (local or global config), or not set when there is none. It is read at startup and again after you switch account or return from the working-tree view. Until you activate a saved account (see Accounts), gct does not set or change this identity; the commit uses whatever Git uses. Once an account is active, its name and email are the identity used for commits, and its GitHub username is the login used for pushes (see Accounts).

First run

On the first run there is no saved configuration, so the date and time start as [not set], the branch defaults to the branch you have checked out, and the message is empty. Fill in the four fields once, then commit. After a successful commit, those values become the defaults for the next run.

Saved configuration

gct stores the last date, branch and message, along with your saved accounts, in a JSON file:

OS Path
Windows %USERPROFILE%\.config\git-commit-tui\config.json
macOS / Linux ~/.config/git-commit-tui/config.json

The commit values are written only after a successful commit (never for a dry run). They use three keys: last_date, last_branch and last_message. Saved accounts are written as soon as you add, edit, delete or activate one (see Accounts). The location can be changed with GCT_CONFIG_DIR, described below.

The file also holds your settings (default mode, remote, safety and experience options; see Config reference) and the optional theme and keys fields (see Theme and keys). All of them can be left out.

[!NOTE] The folder and file are created the first time gct saves after a successful commit (or after you change accounts).

Changing the config folder

Set the GCT_CONFIG_DIR environment variable to an absolute path to keep config.json in that folder instead of the default location. An empty or relative value is ignored and the default location is used.

GCT_CONFIG_DIR=/path/to/folder gct

$env:GCT_CONFIG_DIR = "C:\path\to\folder"
gct

Config reference

Every field is optional, and a config file from an older version still loads. Edit the settings fields with gct --settings, or in the JSON by hand.

Field Meaning Default
default_mode The mode plain gct opens. Any mode name or alias; an unknown value falls back to commit "commit"
default_remote Remote the git modes use (sync, tag push) "origin"
confirm_destructive Ask before Confirm and Danger actions. Discards, published-history rewrites and protected branches are not affected (see Safety model) true
show_commands Show the git command while it runs false
experience "beginner", "normal" or "pro" (see Experience levels). Unknown values act as normal "normal"
protected_branches Branch names guarded by the safety rules; an entry ending in * matches a prefix ["main", "master"]
theme Look of the UI (below) see below
keys Extra main-menu keys (below) none
last_date, last_branch, last_message Remembered commit values empty
accounts, active_account, original Saved accounts and the recorded global Git values (see Accounts) none

GCT_CONFIG_DIR moves the config folder (see Changing the config folder). In the settings screen, settings itself is not offered as a default mode, and the protected branch list cannot be left empty.

Theme and keys

Both fields are optional, and a config file written by an older version (without them) still loads:

{
  "theme": { "accent": "#ff8800", "show_header": true, "show_mascot": true, "show_subtitle": true },
  "keys": { "up": ["k"], "down": ["j"], "quit": ["x"] }
}

theme:

Key Meaning Default
accent Accent colour as "#RRGGBB" (six hex digits; the # is optional). An invalid value is ignored and the built-in cyan/green look is used unset
show_header Show the header at all (title, subtitle and mascot) true
show_mascot Show the mascot in the header true
show_subtitle Show the header subtitle on screens other than the main menu (the main menu always hides it) true

keys adds single-character keys to the main menu, on top of the defaults. The defaults keep working. Each entry maps an action to a list of keys:

Action Same as pressing
up Up
down Down
select Enter
quit Esc
first Home
last End

Only single printable characters are used. Names such as "Enter" or "ctrl-c", empty strings, multi-character strings and whitespace are rejected (ignored). Control-key combinations are never remapped, and w, s, q and Space keep their built-in meaning in the main menu, so binding them has no effect. Keys apply to the main menu only, not to the editors or other screens.

To reset the saved values:

gct --clear-config

This deletes the file and prints Saved configuration cleared. It also deletes saved accounts. It does not undo a global Git account that is still active, so choose git default in the account screen first if you want the original global values back. It works even when the file is corrupt, and it does not need a Git repository or a terminal.

[!TIP] If gct reports invalid config file, run gct --clear-config to delete the broken file.

Accounts

gct can save several Git accounts and switch between them. An account has:

  • a label, the name shown in gct,
  • a git name, written to user.name,
  • an email, written to user.email,
  • a GitHub username, used for push login.

Saved accounts are stored in the config file (see Saved configuration). Two accounts cannot share an email, because GitHub attributes commits by email, so gct rejects a duplicate.

Using accounts

Choose Account in the main menu to open the picker. Pick a saved account to make it active, or pick git default to stop using a gct account. The Account row shows the active account's label. With the Account row selected, Left / Right switch to the previous / next account without opening the picker (git default, then your saved accounts, wrapping around).

Activating an account sets these three global Git settings:

  • user.name
  • user.email
  • credential.https://github.com.username

[!WARNING] Activating an account changes global Git config. Every commit and push from every tool on this machine uses it (terminal, VS Code and others), not only gct. Before the first activation, gct records the global values it finds. Choosing git default, or deleting the active account, restores those recorded values. Switching between saved accounts only rewrites the three settings above.

[!NOTE] A repo-local user.name or user.email does not change what gct commits as: with an active account, gct passes the account's name and email to the commit explicitly, which takes precedence over repo-local settings. gct never edits repo-local settings, and the final summary warns when the repository sets its own value. Plain git commit outside gct still uses the repo-local identity.

Amend keeps the original author, as Git does by default. Only the committer changes to the active account.

Commits and pushes use the active account. A commit records the active account's name and email (passed to Git for that commit, so they win over repo-local user.name and user.email). A push authenticates as the active account's GitHub username: gct runs git -c credential.https://github.com.username=<login> push ..., which wins over a repo-local credential.https://github.com.username, and Git Credential Manager picks the login from it.

Push login: Git Credential Manager keeps one GitHub login per host, so the first push after switching accounts may open a browser window to sign in as the new account. Apart from the one profile request described below, gct never reads or stores tokens.

[!IMPORTANT] Push as the account that can write to the repository. If the repository is owned by a different GitHub account, or by an organization you belong to through another account, activate that account before you push.

[!WARNING] A 403 from GitHub during a push means the active account cannot write to that repository. gct shows Git's error text and does not switch accounts for you. The commit stays local. Activate an account with write access (Left / Right on the Account row), then choose Push only in the menu, or run gct --push-only, to push the existing commit without creating a new one.

Managing accounts (gct --account)

Run gct --account to open the account screen. The first row is git default, followed by the saved accounts. You can add, edit, delete and activate accounts from here.

Key Action
Up / Down, w / s (any case) Move the selection
Enter Set the selected account as active. On git default, stop using a gct account
a (any case) Add an account. Enter a local label (for example account 1) and the GitHub username. gct opens the browser to sign in as that user, then fills in the name and email from your GitHub profile
l (any case) Sign in again to the selected account, then refresh its name and email from GitHub
r (any case) Refresh the selected account's name and email from GitHub, without signing in again
e (any case) Edit the selected account's label and display name
d (any case) Delete the selected account. gct asks for confirmation first
Esc / q (any case) Leave the account screen

The header shows the git identity that is active now (Active in git: Name <email>), read from your git config on every frame. Each account row shows its display name (or its email if the name is empty), its email, its GitHub username, signed in or not signed in, and (active) for the account git uses.

Email comes from your public GitHub email when there is one. Otherwise gct uses GitHub's no-reply address (ID+username@users.noreply.github.com), which still attributes commits to your account.

[!WARNING] To read your profile, gct asks Git Credential Manager for the GitHub token and uses it for one request to api.github.com. The token is kept in memory only. gct never writes it to a file or prints it.

Usage

Main menu

The header shows the mascot (when the terminal is large enough), then three lines:

  • Branch: the branch that is checked out.
  • GitHub: the Git user.name as a tag, or not set.
  • A working-tree tag: Working tree clean, or Working tree: N changes, followed by (click to view). Clicking it opens the full list (see View working tree below). The count is read when gct starts and refreshes after you open View working tree.

Under the header, the menu shows MISSION CONTROL [n/4 FIELDS READY] and these rows, in this order:

Row What it does Left / Right
Edit date Opens the date mask Date minus / plus one day (from today when the date is not set)
Edit time Opens the time mask Time minus / plus one minute, wrapping at midnight, seconds kept (from the current time when not set)
Edit branch Sets the branch to push to Cycles through your local branches, wrapping around
Edit message Opens the inline message editor (see Text editors)
Edit msg (editor) Opens the message in an external editor
Edit options Asks the amend and dry-run questions (the row shows normal, amend, dry-run or amend, dry-run) Cycles normal, amend, dry-run, amend, dry-run
View history Opens the git history screen (see below)
View working tree Shows every git status --short line, read fresh. These are the files the commit stages. Scroll with Up/Down, w/s, PgUp/PgDn, Home/End; Esc/q goes back
Account Opens the account picker. The row shows the active account (see Accounts) Previous / next account (git default, then your saved accounts, wrapping around)
Push only Asks Push to origin/<branch>?, then pushes your existing local commits without creating a commit (see Push only)
Finalize & commit Validates the fields, shows the summary, and runs the commit

A separator line sits between Push only and Finalize & commit. The selected row that Left / Right can change shows ◀ value ▶.

Key Action
Up / Down, w / s (any case) Move the selection (the separator row is skipped)
Tab / Shift+Tab Move to the next / previous row
Home / PgUp Jump to the first row
End / PgDn Jump to Finalize & commit
Left / Right Change the value of the selected row, as listed in the table above
Enter / Space Open the selected row
Mouse click Click a row to select and open it. Click the working-tree tag in the header to open the working-tree view
Esc / q (any case) Quit
Ctrl+C Quit

On a short terminal the menu scrolls so the selected row stays visible. The hint line at the bottom shortens when the terminal is narrow.

If you try to finalize with a missing or invalid field, the menu stays open and shows the problem in red: Please set a valid date, Please set a valid time (HH:MM:SS), Please choose a branch, or Please write a commit message.

[!NOTE] gct refuses to run when HEAD is detached. Check out a branch first, because a commit or push from a detached HEAD would not go to a branch.

History

Choose View history in the menu to read the repository without leaving gct. The screen has two tabs:

  • Recent commits: the last 200 commits, with the short hash, date, decorations (branches and tags) and subject.
  • Remote branches: the branches under git branch -r, with origin/HEAD left out.

The top line shows the current branch and its upstream, or no upstream. In a repository with no commits, the screen shows an empty list.

Key Action
Tab Switch between Recent commits and Remote branches
Up / Down, w / s (any case) Scroll one line
PageUp / PageDown Scroll one page
Home / End Jump to the top or bottom
Esc / q (any case) Return to the menu
Ctrl+C Quit

Date and time masks

Each digit fills the highlighted slot and the cursor moves to the next one. Separators are fixed.

Key Action
0-9 Type a digit into the highlighted slot
Left / Right Move between slots
Home / End Jump to the first / last slot
n (any case) Fill in today's date (date mask) or the current time (time mask)
y (any case) Fill in yesterday (date mask only)
r (any case) Fill in a random time between 09:00:00 and 18:00:00 (time mask only)
- / + Date mask: one day back / forward. Time mask: one minute back / forward, wrapping at midnight with the seconds kept. Ignored while any slot is blank
Backspace Clear the current slot and move left
Delete Clear the current slot
Enter Save (rejects incomplete or invalid values)
Esc Cancel and keep the previous value
Ctrl+C Quit gct

When a mask opens with no valid value, it starts with the current year (date) or 00 hours (time) filled in and the rest blank.

Validation messages: Complete all fields before continuing, Not a valid calendar date (leap years are handled), and Time out of range (00:00:00 - 23:59:59).

Text editors

The branch field uses the single-line editor. The message uses the multiline editor, which works like Notepad.

Key Single line (branch) Multiline (message)
Typing, Left / Right, Backspace, Delete Edit text Edit text
Home / End Start / end of the text Start / end of the current line
Ctrl+Home / Ctrl+End Start / end of the text Start / end of the text
Ctrl+Left / Ctrl+Right Jump one word Jump one word
Up / Down Not used Move one line, keeping the column where the line is long enough
PgUp / PgDn Not used Move one screenful of lines
Enter Save and close New line
Ctrl+Enter Save and close Save and close
Tab, then Enter Not used Focus the Save & go back button, then press it
Esc Cancel and keep the previous value Leave without saving (keeps the value the editor opened with)
Ctrl+C Quit gct Quit gct

The message editor ends with a green Save & go back button on its last row. Click it (anywhere on that row) to save and return to the main menu. Ctrl+Enter does the same (it needs a terminal that reports Ctrl+Enter), and Tab highlights the button so Enter presses it; any other key returns to the text. An empty message shows a red Message is required instead of closing. Esc leaves without saving. There are no Ctrl+S, F2 or word-delete shortcuts; Backspace and Delete remove one character.

The editor shows a blinking bar cursor where the terminal supports changing the cursor shape, and puts the cursor back afterwards. Long messages scroll to keep the cursor visible.

An empty value is rejected with Value is required (single line) or Message is required (multiline). Saved messages are trimmed.

Push only

Choose Push only in the menu to push commits that already exist, without creating a commit. It needs a branch value and asks Push to origin/<branch>? (default Yes). The branch is the Edit branch value. If the active account's login cannot be verified, nothing is pushed and the reason is shown.

  • The result is shown in the menu: Pushed to origin/<branch> or Push failed: <git error>. A failed push never closes gct, so you can fix the problem (for example switch account) and choose Push only again.
  • If Edit options is set to amend, or the push of an amended commit failed earlier, the question reads Push to origin/<branch> with --force-with-lease (amended commit)? and the push uses --force-with-lease. After a failed push of an amended commit, Push only keeps using --force-with-lease until a push succeeds.
  • The same operation is available without the TUI as gct --push-only (see Commit without the TUI).

After Finalize & commit creates the commit, a failed stage, commit or push also leaves you in the menu with the error shown in red. A failed push shows Committed locally, but push failed: <error>. Use "Push only" to retry. The commit is kept, and your last values are already saved.

While staging, committing and pushing, a spinner and a message such as Creating commit... or Pushing to origin/<branch>... are shown.

Confirmation prompts

Prompt Keys Default on Enter
Amend the last commit instead of creating a new one? Y / N / Enter No
Preview only (dry run, do not commit/push)? Y / N / Enter No
Proceed with these actions? (final summary) Y / N / Enter Yes
Push to GitHub? (after the commit) Y / N / Enter Yes
Push to origin/? (Push only) Y / N / Enter Yes
Press any key to exit (final screen) Any key -

Ctrl+C at the summary prompt cancels without committing and quits. Ctrl+C at the push question does not undo the commit: it is treated as "no push", and gct shows Done. commit -> local only (no push).

[!WARNING] The Edit branch value only selects the push target. The commit is always created on the branch that is currently checked out. The push runs git push origin <branch> for the value you entered, so make sure the two match.

Commit modes

Choose these under Edit options (Enter asks the two questions, Left / Right cycle through the four combinations). Both reset to off each time gct starts.

Normal commit

Runs, in order:

git add .
git commit -m "<message>"

The date you entered is passed to Git as GIT_AUTHOR_DATE and GIT_COMMITTER_DATE. git add . stages from the directory where you started gct, and it stages all changes in that directory tree.

Amend

Runs git add . and then git commit --amend -m "<message>". The date fields are applied to the amended commit as well, and the message field is still required.

[!CAUTION] When you push an amended commit, gct uses git push --force-with-lease origin <branch>. This rewrites the remote branch. The lease refuses the push if the remote has commits you have not fetched, but the previous commit on the remote is still replaced.

Dry run

Dry run validates the fields and then prints the commands it would run, without staging, committing, saving the configuration or pushing:

Dry run - commands that would be executed:
  git add .
  git commit -m "<message>" (author/committer date: <date>)

In the TUI no push line is printed because a dry run never asks to push. With flags, --dry-run --push also prints git push origin <branch>. Dry run combines with amend, and the printout then shows commit --amend.

External editor

Choose Edit msg (editor) to edit the message in an editor. gct writes the current message to a temporary file, leaves the TUI, runs the editor on that file, and reads it back when the editor exits. The message is trimmed, and an empty result is rejected.

The editor is chosen in this order:

  1. VISUAL
  2. EDITOR
  3. notepad on Windows
  4. vi on macOS and Linux

The variable can include arguments, which are split on spaces. The temporary file path is added last.

$env:EDITOR = "code --wait"
gct

[!NOTE] The editor must block until you close it (for example, code --wait). If it returns immediately, gct reads the file before you have written anything.

Troubleshooting

Message Meaning and fix
gct needs an interactive terminal; run it directly in a shell Stdin or stdout is not a terminal. Run gct from a shell window.
Not a git repository The current branch or git status could not be read. Run gct inside a repository.
could not start git <args> The git program could not be started. Check that Git is on PATH.
git command failed A Git command failed without printing an error. Run the same command by hand to see why.
Staging all files failed: <git message> git add . failed. The Git message follows the colon.
<git message> after Error: during commit or push Git rejected the commit or push. The text is Git's own stderr, for example a rejected push.
could not start git commit The git commit process could not be started.
Commit failed: <git message> In the TUI, git commit failed (for example a hook rejected it or there was nothing to commit). gct stays open; fix the cause and finalize again.
Committed locally, but push failed: <error>. Use "Push only" to retry. The commit exists but the push failed. Fix the cause (for example switch to an account with write access), then choose Push only.
Push failed: <git message> A push from Push only or gct --push-only failed. The text is Git's own error.
Not pushed: <reason> / Not committed: <reason> The active account's GitHub login could not be verified, so gct stopped before pushing or committing.
Set a branch to push first Push only was chosen while the branch value is empty.
Please set a valid date / Please set a valid time (HH:MM:SS) / Please choose a branch / Please write a commit message A required field is missing or invalid. Fix it in the menu, then finalize again.
Complete all fields before continuing A date or time mask still has empty slots.
Not a valid calendar date The date does not exist, for example 2026-02-30.
Time out of range (00:00:00 - 23:59:59) The time is not a valid 24-hour time.
Value is required / Message is required An editor was saved empty.
editor command is empty VISUAL or EDITOR is set but contains no program name.
editor exited with status <status> The editor closed with a non-zero status, so the change was discarded.
could not read editor output The temporary file could not be read after the editor closed.
Commit message is required The external editor returned an empty message.
could not locate the home directory No home directory was found, so the config path cannot be built.
could not read <path> / could not write <path> / could not create <path> A file-system error on the config file or its folder. Check permissions.
invalid config file <path> The config file is not valid JSON for gct. Run gct --clear-config.
could not enable terminal raw mode / could not enter terminal UI The terminal does not support the required mode.
Cancelled. (exit code 130) You pressed Ctrl+C, or Esc / q in the main menu. Nothing was committed by this action.

FAQ

Does gct push automatically? No. After the commit it asks Push to GitHub?. The default is Yes, so press n to keep the commit local.

If the push fails, is the commit lost? No. The commit already exists locally and your values are saved. gct stays open and shows the push error in the menu. Fix the cause, then choose Push only (or run gct --push-only) to retry.

Does gct stage only some files? No. Normal and amend modes run git add ., which stages all changes under the directory you started gct in. Stage selectively with Git before running gct if you need that.

Why does the mascot disappear? The mascot is drawn only when the terminal is at least 50 columns wide and 32 rows tall. Below that size the header shows only the title and tagline. You can also turn the mascot off with show_mascot, or the whole header with show_header, in the config (see Theme and keys).

What does the mascot do? It turns its eyes and nose toward your mouse pointer as you move it over the terminal, and its face and status line change with the state (ready, working, done, or error).

Why can't I select text with the mouse? gct turns on mouse capture while it runs, so most terminals stop handling mouse selection. Check your terminal's documentation for a way to bypass this.

Is the dry run saved for next time? No. A dry run never saves the configuration. The date, time, branch and message are remembered only after a real commit.

Why use --force-with-lease for amend? It is a safer force push: it refuses to overwrite remote commits that your local copy has not seen.

Development

Check formatting, lint, and build:

cargo fmt --check

cargo clippy --all-targets -- -D warnings

cargo build

Run the tests:

cargo test

cargo test runs the unit tests and the CLI tests in tests/cli.rs. The CLI tests build a throwaway Git repository and set GCT_CONFIG_DIR (plus a temporary HOME and Git config) so your real gct config and Git settings are not touched. If you write your own tests that run gct, set GCT_CONFIG_DIR to a temporary absolute path as well.

Project layout:

src/main.rs      Entry point, CLI flags, the --agent guide and the commit workflow
src/modes/       One file per mode, plus mod.rs (the mode registry and router) and hub.rs
src/ui.rs        Shared screens for the modes: lists, pagers, confirmations, spinner jobs
src/input.rs     Menu, text and date/time editors, external editor, confirmations
src/terminal.rs  Centered panel, drawing, mouse tracking, and terminal setup/restore
src/mascot.rs    Mascot frames, colors, and the size check
src/git.rs       Git subprocess runners (bounded output, timeouts) and push helpers
src/policy.rs    Confirmation tiers and protected branches
src/safety.rs    Backup refs under refs/gct/backup/
src/repo_state.rs  Reads branch, upstream, changes and in-progress operations
src/history.rs   Commit log reading for the history modes
src/cmdlog.rs    In-memory log of git commands, with secrets masked
src/explain.rs   Plain-language explanations of git terms
src/testutil.rs  Throwaway repositories for tests
src/config.rs    Saved configuration load, save and clear (honours GCT_CONFIG_DIR)
src/accounts.rs  Saved accounts and applying the active one to global Git config
src/gitconfig.rs Reads user.name and user.email from git config
src/model.rs     Values, validation, theme and key settings, date/time adjusters
tests/cli.rs     End-to-end tests for the flag mode

What's new

2.4 (modes)

  • gct is now a multi-mode Git controller with 21 modes in six groups, opened with gct --hub or gct --mode <name> (see Modes). Plain gct still opens the commit TUI unless you set another default_mode.
  • Mode flags: --hub, --settings, --mode, --commit, --stage, --status, --sync, --log, --stash, --undo, --tag.
  • Safety model: confirmation tiers, protected branches, backup refs under refs/gct/backup/ with restore in Undo mode, no raw --force, an optional "show git commands" setting and a Commands log (see Safety model).
  • New settings: default_mode, default_remote, confirm_destructive, show_commands, experience and protected_branches (see Config reference).
  • The git modes need Git 2.30 or newer. The commit, account and settings modes do not.
  • Start mode creates or clones a repository and walks through identity, .gitignore, the first commit, a remote and the first push.

2.3

  • Main menu: new row order (Edit date, time, branch, message, msg (editor), options, View history, View working tree, Account, Push only, Finalize & commit). Left / Right change the date, time, branch, options and account without opening an editor. The header shows Branch, the GitHub (Git user.name) tag and a Working tree label that opens the working-tree view.
  • Message editor works like Notepad, with a clickable Save & go back button (also Ctrl+Enter, or Tab then Enter); Esc leaves without saving. Up/Down, per-line Home/End, Ctrl+Home/End, word jumps, PgUp/PgDn and a blinking bar cursor were added. Ctrl+S, F2 and word delete are not supported.
  • Date and time masks: - and + step by a day or a minute, and r fills a random time between 09:00 and 18:00.
  • Push only menu row and --push-only flag. Failed stage, commit and push no longer close the TUI, a failed push can be retried, and an amended commit is pushed with --force-with-lease.
  • Spinner while staging, committing and pushing.
  • Config file: optional theme and keys settings, and the GCT_CONFIG_DIR environment variable. Older config files still load.

License

Licensed under the MIT License. See LICENSE.