Clarify status-line git changes vs uncommitted working tree state

Summary

The branch-changes status-line item can be misleading because it looks like a local dirty-working-tree indicator, but it also appears to include committed branch diff against the upstream/base branch.

For example, in a clean working tree on main that is ahead of origin/main by several commits, the Codex status line can show something like:

main ? +354 -21

This reads like there are uncommitted local edits, even though:

git status --short --branch
## main...origin/main [ahead 7]

git diff --shortstat
# no output

git diff --cached --shortstat
# no output

git ls-files --others --exclude-standard
# no output

Current behavior

With this config:

[tui]
status_line = ["model-with-reasoning", "project-name", "git-branch", "branch-changes"]

branch-changes may display aggregate insertions/deletions from committed branch divergence, not just uncommitted working tree changes.

Why this is confusing

Many CLI tools use a compact marker such as * to mean "the working tree has uncommitted changes". In Codex, +N -N beside the branch can be read the same way, but it can also mean "this branch has local commits not pushed to upstream".

That makes it hard to glance at the status line and answer the basic question:

Do I currently have uncommitted local changes?

Proposed options

Any of these would make the status line clearer:

1. Add a separate git-dirty status-line item that only indicates uncommitted working tree/index/untracked changes, for example * or dirty.
2. Add a separate git-ahead-behind item for upstream divergence, and keep it visually distinct from dirty state.
3. Rename or document branch-changes so users know it is not equivalent to dirty working-tree state.
4. In /statusline, describe branch-changes as branch/base diff rather than local uncommitted changes, if that is the intended behavior.

Related

This is related to #22697, but narrower: this issue is specifically about avoiding ambiguity between committed branch divergence and uncommitted working tree state.

Environment

codex-cli 0.140.0
Windows / PowerShell