v0.4.0 — Watch mode, dirty filter & man page

[sven42xyz]

Target release: v0.4.0 (minor — backward-compatible features).

Two headline features for inspecting and acting on many repos at once, plus
robustness fixes, a restructured README and a man page.

✨ Watch mode (-w / --watch)

• Live, in-place status table on the alternate screen buffer (scrollback untouched), cursor hidden, default 3 s interval (-w 10 to change).
• Interactive keys act on the whole tree without leaving the view: f fetch, p pull, s switch, r refresh now, q/Ctrl-C quit. A spinner animates the action verb and the table stays on screen while it runs.
• s opens a branch picker: recently-active branches (most recent first), type-to-filter, ↑/↓ navigation, Tab/Enter to choose — drawn in place below the table.
• Always restores the terminal on exit, including on SIGINT / SIGTERM. No ncurses dependency — raw ANSI escapes + termios only. Requires an interactive terminal (stdin + stdout).

🩹 Dirty filter (--dirty / --no-dirty)

• Lists only repos that aren't both clean and in sync (staged/modified/untracked, ahead/behind, diverged or detached HEAD).
• Summary still counts all repos and appends (N hidden). Works one-shot and under -w.
• --no-dirty opts out of dirty_only from the config for a single run.

⚙️ Config

• New ~/.gitlsrc keys watch_interval and dirty_only; CLI flags override them.

🐛 Fixes

• Column overflow (also affected one-shot mode): long branch names made rows wrap and corrupt the table. NAME/BRANCH columns are now capped to the terminal width; piped output keeps full width.
• Stale columns in watch mode: a narrower refresh (e.g. switching to a shorter branch) left a phantom WHEN/STATUS column — each rewritten line is now cleared to its end.

📖 Docs & packaging

• README restructured around watch mode (value-first layout, TOC, status/indicator reference centralised, --help moved to a Reference section).
• gitls(1) man page; make install/uninstall honour DESTDIR; RPM spec and Homebrew formula updated.

✅ Testing

• make test → 27 unit + 45 integration + 17 PTY, clean build with -Wall -Wextra.
• tests/watch_pty.py drives watch mode through a pseudo-terminal (with a tiny VT emulator), including a regression test for the stale-columns bug.
• All 7 CodeRabbit review findings addressed and resolved.

Remaining for the 0.4.0 tag

• Tag v0.4.0, then bump Version in packaging/gitls.spec and the url/sha256 in packaging/gitls.rb to the release tarball (sha256 only computable from the published artifact).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added watch mode (-w/--watch) with live in-place table refresh and interactive controls (fetch, pull, branch switching, and filtering)
  • Added dirty-only filtering (--dirty) to display only repositories that are not clean and in-sync
  • Added configuration support for watch interval and dirty-only settings in ~/.gitlsrc

• Bug Fixes

  • Fixed table rendering corruption with branch name truncation and stale column cleanup in watch mode
  • Improved table visibility during actions

• Documentation

  • Added man page documentation
  • Updated README with watch mode and filtering guides

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c4b34247-1396-40d1-9c6f-ec74b7aa7e1e

📥 Commits

Reviewing files that changed from the base of the PR and between d071ec8 and 354c57f.

📒 Files selected for processing (12)

• CHANGELOG.md
• Makefile
• README.md
• config.c
• display.c
• gitls.1
• main.c
• packaging/gitls.rb
• packaging/gitls.spec
• tests/integration.sh
• tests/watch_pty.py
• watch.c

---

📝 Walkthrough

Walkthrough

Introduces gitls watch mode (-w) with live in-place terminal refresh, key-driven actions and branch picker, dirty-only filtering with hidden counts, new CLI/config controls, terminal-width-safe table rendering, expanded tests, and updated README/man/changelog plus build and packaging metadata for 0.4.0.

Changes

Watch Mode and Dirty Filtering

Layer / File(s)	Summary
CLI options, config parsing, and exported contracts gitools.h, main.c, config.c	Adds exported watch/dirty globals and prototypes; parses -w [n], --dirty, --no-dirty; validates watch-mode constraints/TTY requirements; and loads watch_interval/dirty_only from config with numeric validation.
Repository collection and status-table foundations repo.c, display.c, main.c	Adds git availability and recent-branch collection/freeing, suppresses inter-phase spinner text during watch processing, introduces term_width/ellipsize/EOL, and centralizes dirty-aware table rendering via print_status_table.
Watch loop and interactive picker runtime watch.c, main.c	Implements alternate-screen/raw terminal lifecycle, signal-aware event loop, key decoding, filterable branch picker, footer redraw, one-shot fetch/pull/switch action handling, and watch-mode early-return execution path from main.
Unit, integration, and PTY watch-mode validation tests/unit.c, tests/integration.sh, tests/watch_pty.py, Makefile	Adds ellipsize unit coverage, dirty-filter and watch-guard integration tests, a PTY-driven interactive watch-mode harness (including picker and redraw regressions), and Makefile logic to run PTY tests when python3 is available.
User docs, man page, and config examples README.md, gitls.1, gitlsrc.example	Documents watch mode behavior/keys, dirty filtering semantics, config defaults and precedence, updated CLI reference, and adds a full gitls(1) manual page plus example config keys.
Build, install, and release packaging updates CHANGELOG.md, Makefile, packaging/*	Records 0.4.0 release notes; updates build version/source list and DESTDIR-aware install/uninstall paths; bumps package metadata and adds packaging assertions for installed man page and docs.

Sequence Diagram

sequenceDiagram
  participant User
  participant Main
  participant Watch
  participant Repo
  participant Display
  participant Terminal

  User->>Main: run gitls -w
  Main->>Watch: run_watch abs_dir
  Watch->>Terminal: enable alternate screen and raw mode
  loop refresh interval or key input
    Watch->>Repo: find_repos and process_all_repos
    alt key requests fetch pull or switch
      Watch->>Repo: execute action
      Watch->>Terminal: render spinner
    end
    Watch->>Display: compute widths and print status table
    Watch->>Display: print footer
  end
  User->>Watch: press q or Ctrl-C
  Watch->>Terminal: restore terminal state
  Watch-->>Main: return

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Possibly related PRs

• sven42xyz/gitools#1: Adds the earlier config and fetch/pull groundwork that this PR extends with watch_interval, dirty_only, and watch-mode behavior integration.

Poem

🐇 I tapped -w and watched it gleam,
Branches hopped through a tidy stream.
Dirty leaves stayed in my sight,
Clean ones tucked away just right.
Cursor bows, then home I bound—soft paws, silent ground.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 59.26% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'v0.4.0 — Watch mode, dirty filter & man page' clearly reflects the major changes in the PR: watch mode and dirty filter features are implemented and documented throughout the changeset.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/watch-and-dirty

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 7

🧹 Nitpick comments (1)

README.md (1)

15-16: 📐 Maintainability & Code Quality | ⚡ Quick win

Documentation is comprehensive and accurate, but three fenced code blocks need language specifiers.

All feature descriptions, keybindings, config keys, defaults, and workflow explanations align precisely with the implementation. The dirty filter definition (staged/modified/untracked, ahead/behind, diverged, detached HEAD) matches repo_is_dirty() in display.c exactly. The watch mode terminal behavior (alternate screen, restore on SIGINT/SIGTERM, raw ANSI) is well documented. However, three output examples lack language specifiers on their fenced code blocks (lines 168, 201, 237). Specifying a language improves content rendering by using the correct syntax highlighting for code.

📝 Proposed fix: Add language specifiers to fenced code blocks

-Line 168:
-```
+```text
 Scanned: /home/me/projects
 
 NAME            BRANCH     SYNC  WHEN         STATUS
 ...
 
 
 f fetch · p pull · s switch · r refresh · q quit
 interval 3s · /home/me/projects · switched to main
-```
+```

-Line 201:
-```
+```text
 ... status table ...
 
 f fetch · p pull · s switch · r refresh · q quit
 interval 3s · /home/me/projects
 
 switch all clean repos to: dev▏
 ↑/↓ navigate · Tab/Enter select · Esc cancel
 ❱ develop
   hotfix
-```
+```

-Line 237:
-```
+```text
 gitls --dirty ~/projects
 
 NAME            BRANCH     SYNC  WHEN         STATUS
 ...
 
 9 repos · 6 clean · 3 dirty · 1 behind (7 hidden)
-```
+```

Also applies to: 71-72, 95-102, 156-229, 230-249, 318-330

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` around lines 15 - 16, Three fenced code blocks in README examples
are missing language specifiers; update the relevant triple-backtick fences (the
examples showing the status table / watch mode and the gitls --dirty output) to
include a language tag (e.g., ```text) so syntax highlighting renders correctly.
Locate the blocks that currently start and end with plain ``` around the
status-table/watch-mode snippets (the examples containing "Scanned:
/home/me/projects", the "switch all clean repos to:" interactive snippet, and
the "gitls --dirty ~/projects" output) and change their opening fences to
```text (also apply same change to the other nearby fenced blocks in the listed
ranges to keep consistency). Ensure only the opening fence is changed to include
the language specifier and close fences remain ``` as-is.

Source: Linters/SAST tools

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@config.c`:
- Around line 109-112: The watch_interval parsing branch (strcmp(key,
"watch_interval") ...) currently casts strtol() to int and only checks iv >= 1;
change it to parse into a long (e.g., long lv = strtol(val, &end, 10)), include
<errno.h>, check errno == ERANGE or *end != '\0' to reject invalid/overflowed
parses, then enforce bounds (ensure lv >= 1 and if lv > INT_MAX clamp to
INT_MAX) before assigning to opt_watch_interval (cast to int after clamping);
preserve the existing behavior for valid inputs and reject/ignore invalid ones.

In `@display.c`:
- Around line 17-26: The function term_width currently consults
getenv("COLUMNS") even when STDOUT is not a TTY, causing piped/scripted output
to be wrongly capped; change term_width so COLUMNS is only used when stdout is a
TTY (i.e., only after isatty(STDOUT_FILENO) succeeds), and return 0 immediately
when stdout is not a TTY; update the logic in the term_width function (refs:
term_width, isatty, ioctl/TIOCGWINSZ, getenv("COLUMNS"), ws.ws_col) to avoid
reading COLUMNS for non-TTY output.

In `@main.c`:
- Around line 175-177: The guard for watch mode only checks stdout TTY; update
the condition in main (the opt_watch block using isatty) to require both stdin
and stdout TTYs (use isatty(STDIN_FILENO) && isatty(STDOUT_FILENO)) and adjust
the fprintf message to indicate that -w requires an interactive terminal on both
stdin and stdout so redirected stdin won't bypass the check.
- Around line 65-66: Update the help/usage string in main.c to accurately
document the accepted options: add the long form "--watch" next to the short
"-w" entry (e.g. "  -w, --watch [n]  Watch mode: refresh the table every n
seconds (default: 3)\n") and restore the full description for the dirty option
to match behavior (e.g. "  --dirty      Only list repos that are not clean or
not in sync\n"); edit the same string literal/block that currently contains the
two lines shown so the printed --help matches the parser's accepted flags and
semantics.
- Around line 149-150: The current CLI parsing sets opt_dirty_only when
"--dirty" is present but never allows CLI to override a true value from
load_config(); update the argument handling so an explicit CLI decision wins:
either (A) add a negating flag (e.g., "--all" or "--no-dirty") and check
strcmp(argv[i], "--no-dirty") to set opt_dirty_only = false, or (B) track
whether the user supplied a dirty-related flag (e.g., a boolean
cli_dirty_specified) and apply CLI value after load_config(); modify the parsing
around strcmp(argv[i], "--dirty")/opt_dirty_only and ensure the help text
mentions the new opt-out flag, and add a regression test covering config with
dirty_only=true plus an explicit CLI opt-out to confirm CLI overrides config.

In `@tests/watch_pty.py`:
- Around line 179-187: The current Watcher.finish() calls os.waitpid(self.pid,
0) which can block forever; change it to a bounded wait: repeatedly call
os.waitpid(self.pid, os.WNOHANG) in a short loop up to a timeout (e.g. a few
seconds) checking for a non-zero pid return, sleeping briefly between polls; if
the timeout elapses and the child still exists, send a termination signal
(os.kill(self.pid, signal.SIGKILL) or SIGTERM first) and then reap it with
os.waitpid; update Watcher.finish to use os.WNOHANG, a timeout loop, and signal
handling (import signal) so the test cannot hang indefinitely.

In `@watch.c`:
- Around line 283-291: Install the cleanup hooks (call atexit(restore_terminal)
and set up sigaction with sa.sa_handler = on_signal for SIGINT and SIGTERM)
before making any terminal state changes; move the atexit and sigaction setup so
it runs prior to write_seq(ALT_SCREEN_ON), write_seq(CURSOR_HIDE), and
enter_raw_mode() to ensure restore_terminal runs on exit or signals.

---

Nitpick comments:
In `@README.md`:
- Around line 15-16: Three fenced code blocks in README examples are missing
language specifiers; update the relevant triple-backtick fences (the examples
showing the status table / watch mode and the gitls --dirty output) to include a
language tag (e.g., ```text) so syntax highlighting renders correctly. Locate
the blocks that currently start and end with plain ``` around the
status-table/watch-mode snippets (the examples containing "Scanned:
/home/me/projects", the "switch all clean repos to:" interactive snippet, and
the "gitls --dirty ~/projects" output) and change their opening fences to
```text (also apply same change to the other nearby fenced blocks in the listed
ranges to keep consistency). Ensure only the opening fence is changed to include
the language specifier and close fences remain ``` as-is.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b385fa17-a905-4c13-b97b-863e793332bc

📥 Commits

Reviewing files that changed from the base of the PR and between cffe622 and 91eec2d.

📒 Files selected for processing (13)

• CHANGELOG.md
• Makefile
• README.md
• config.c
• display.c
• gitlsrc.example
• gitools.h
• main.c
• repo.c
• tests/integration.sh
• tests/unit.c
• tests/watch_pty.py
• watch.c