git-custom-cli 2.4.0

Fast, keyboard-driven terminal UI for dated Git commits
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
# 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](#modes)), with confirmations and backups for risky actions (see [Safety model](#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](#theme-and-keys)).
- Saved Git accounts (label, name, email, GitHub username) that you can switch between. See [Accounts](#accounts).
- Multi-mode controller: stage, branch, sync, stash, log, undo, conflicts, tags and more, opened with `gct --hub` or `gct --mode <name>`. See [Modes](#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](#commit-without-the-tui) works without one.
- Run it from inside a Git repository, except for the modes marked as working outside one in [Modes](#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](#commit-without-the-tui)).

## Installation

Install the published crate:

```sh
cargo install git-custom-cli
```

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

To build from source instead:

```sh
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](#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:

```sh
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:

```sh
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](#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](#usage) and [Commit modes](#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](#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](#accounts).

**settings** edits the values in [Config reference](#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](#show-git-commands-and-the-commands-log).

**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](#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](#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](#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](#config-reference)) and the optional `theme` and `keys` fields (see [Theme and keys](#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.

```sh
GCT_CONFIG_DIR=/path/to/folder gct
```

```powershell
$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](#safety-model)) | `true` |
| `show_commands` | Show the git command while it runs | `false` |
| `experience` | `"beginner"`, `"normal"` or `"pro"` (see [Experience levels](#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](#accounts)) | none |

`GCT_CONFIG_DIR` moves the config folder (see [Changing the config folder](#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:

```json
{
  "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:

```sh
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](#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](#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](#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](#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 | Leave without saving (keeps the value the editor opened with) |
| 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](#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/<branch>? (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:

```text
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:

```text
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.

```powershell
$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](#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:

```sh
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo build
```

Run the tests:

```sh
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:

```text
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](#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](#safety-model)).
- New settings: `default_mode`, `default_remote`, `confirm_destructive`, `show_commands`, `experience` and `protected_branches` (see [Config reference](#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](LICENSE).