git-custom-cli 2.3.2

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
# git-custom-cli (`gct`)


`gct` is a keyboard-driven terminal UI for making Git commits with a custom date and time, a branch to push to, and a multiline message. 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).

## 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.

> [!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).

### 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.

## 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.

Two optional fields customise the look and the keys. Both can be left out. See [Theme and keys](#theme-and-keys).

> [!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
```

#### 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 flag, and the commit workflow
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 calls (branch, status, add, commit, push)
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 in 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).