# TUICR `commit_order` and `initial_commit_selection` Options: Configuring the Commit Selector UI

> Master TUICR's commit selector UI. Learn how commit_order and initial_commit_selection options customize commit sorting and selection for efficient workflow management.

- Repository: [Almog Gavra/tuicr](https://github.com/agavra/tuicr)
- Tags: configuration
- Published: 2026-08-02

---

**The `commit_order` option controls how commits are sorted in TUICR's commit selector UI (`chronological` or `topological`), while `initial_commit_selection` sets whether the selector opens with a single commit pre-selected or a full range selected.**

TUICR is a terminal-based UI for code review that provides flexible commit navigation. The `commit_order` and `initial_commit_selection` configuration options let you customize how the commit selector presents and pre-selects commits when reviewing pull requests or branches. These options are defined in the configuration system and consumed by the UI rendering logic in [`src/ui/inline_commit_selector.rs`](https://github.com/agavra/tuicr/blob/main/src/ui/inline_commit_selector.rs) and state initialization in [`src/app/commits.rs`](https://github.com/agavra/tuicr/blob/main/src/app/commits.rs).

## What `commit_order` Controls

The `commit_order` option determines the **sorting strategy** applied to commits before they appear in the selector list.

### Available Values

| Value | Behavior | Use Case |
|-------|----------|----------|
| `chronological` | Newest commit appears first, sorted by timestamp | Default; useful for time-based review workflows |
| `topological` | Maintains parent-child relationships using Git's topological sort | Preserves branch structure; better for understanding merge history |

### Where It's Implemented

In [`src/ui/inline_commit_selector.rs`](https://github.com/agavra/tuicr/blob/main/src/ui/inline_commit_selector.rs), the `CommitSelector::new` function reads this configuration value and applies it when building the commit list:

```rust
// Simplified excerpt showing commit order application
fn build_commit_list(commits: Vec<Commit>, order: CommitOrder) -> Vec<CommitRow> {
    let mut sorted = commits;
    match order {
        CommitOrder::Chronological => sorted.sort_by_key(|c| c.timestamp),
        CommitOrder::Topological => sorted = git_topo_sort(sorted),
    }
    sorted.iter().map(|c| CommitRow::from(c)).collect()
}

```

The order affects **navigation key behavior** (`j/k` movement through the list) and how commits are **visually grouped** in the UI.

## What `initial_commit_selection` Controls

The `initial_commit_selection` option determines **which commits are pre-selected** when the commit selector UI first opens.

### Available Values

| Value | Behavior | Use Case |
|-------|----------|----------|
| `single` | Only the most recent commit is selected | Default; focused, single-commit review |
| `range` | All commits in the branch are selected | Reviewing an entire feature branch at once |

### Where It's Implemented

In [`src/app/commits.rs`](https://github.com/agavra/tuicr/blob/main/src/app/commits.rs), the `initial_commit_selection` function (as implemented in `agavra/tuicr`) creates the starting state:

```rust
// Internal: Determining the initial selection mode
fn initial_commit_selection(cfg: &Config) -> CommitSelectorState {
    match cfg.initialcommitselect

```

This function returns either `CommitSelectorState::Single` with the latest commit SHA, or `CommitSelectorState::Range` with all commit SHAs, depending on the configuration value.

## Configuration in Practice

### Config File Setup

Add these options to your TUICR configuration file (typically `~/.config/tuicr/config.toml` or specified via command line):

```toml

# ~/.config/tuicr/config.toml

commit_order = "topological"
initial_commit_selection = "range"

```

### Runtime Changes

Both options can be modified during a session using TUICR's command interface:

- `:commit_order topological` — switch to topological sorting
- `:initial_commit_selection range` — enable range selection mode

Changes take effect immediately for the current session and are stored in the in-memory `Config` instance.

### Programmatic Access

```rust
// Example: Programmatic configuration (e.g., for custom plugins)
let mut cfg = tuicr::config::Config::load().unwrap();
cfg.commit_order = tuicr::config::CommitOrder::Topological;
cfg.initial_commit_selection = tuicr::config::InitialCommitSelection::Range;
cfg.save().unwrap();

```

## Key Source Files

| File | Purpose |
|------|---------|
| [`src/config/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/config/mod.rs) | Defines `CommitOrder` and `InitialCommitSelection` enums; parses [`config.toml`](https://github.com/agavra/tuicr/blob/main/config.toml) |
| [`src/ui/inline_commit_selector.rs`](https://github.com/agavra/tuicr/blob/main/src/ui/inline_commit_selector.rs) | Renders commit list; applies `commit_order` during list construction |
| [`src/app/commits.rs`](https://github.com/agavra/tuicr/blob/main/src/app/commits.rs) | Initializes selector state based on `initial_commit_selection` |

The `Config` struct in [`src/config/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/config/mod.rs) exposes these as typed fields with default values (`commit_order` defaults to `chronological`, `initial_commit_selection` defaults to `single`).

## Summary

- **`commit_order`** — controls commit sort order: `chronological` (timestamp-based) or `topological` (Git history structure)
- **`initial_commit_selection`** — sets opening selection mode: `single` (latest commit only) or `range` (all commits)
- Both options are defined in [`src/config/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/config/mod.rs), consumed by [`src/ui/inline_commit_selector.rs`](https://github.com/agavra/tuicr/blob/main/src/ui/inline_commit_selector.rs) and [`src/app/commits.rs`](https://github.com/agavra/tuicr/blob/main/src/app/commits.rs)
- Configure via [`config.toml`](https://github.com/agavra/tuicr/blob/main/config.toml), runtime commands, or the Rust API
- Defaults favor focused review: chronological order with single-commit selection

## Frequently Asked Questions

### How do I make TUICR show commits in Git's natural history order instead of by date?

Set `commit_order = "topological"` in your configuration. This uses Git's `--topo-order` logic, which preserves parent-child relationships and shows commits in the order they were applied to branches, rather than by timestamp. This is particularly useful when reviewing complex merge histories where chronological order would interleave commits from different branches.

### Can I start TUICR with all commits selected for a range review by default?

Yes. Set `initial_commit_selection = "range"` in your [`config.toml`](https://github.com/agavra/tuicr/blob/main/config.toml). When the commit selector opens, all commits in the current branch will be pre-selected, enabling immediate range-review mode without manual selection. The default `single` value is designed for focused, commit-by-commit review workflows.

### Do these settings persist between TUICR sessions?

Configuration file changes persist permanently. Runtime changes made via commands like `:commit_order` or `:initial_commit_selection` are stored in the in-memory `Config` instance for the current session only. To make runtime changes permanent, modify your [`config.toml`](https://github.com/agavra/tuicr/blob/main/config.toml) directly or call `cfg.save()` if using the programmatic API in [`src/config/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/config/mod.rs).

### Where are the default values defined in the TUICR source code?

Default values are specified in [`src/config/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/config/mod.rs) where the `Config` struct is defined. The implementation uses standard Rust defaults: `commit_order` defaults to the `Chronological` variant, and `initial_commit_selection` defaults to `Single`. These defaults are applied when parsing configuration files that omit these keys.