feat: add watch mode for auto-refreshing diffs (#96)

## Summary

When working on a branch, it's useful to leave diffnav open in a
terminal tab and have it automatically reflect the latest changes. This
adds `--watch` mode, which periodically re-runs a diff command and
refreshes the TUI.

```sh
diffnav --watch
diffnav --watch --watch-cmd "git diff main..." --watch-interval 5s
```

## Details

- New flags: `--watch` (`-w`), `--watch-cmd` (default: `git diff`),
`--watch-interval` (default: `2s`)
- Watch tick/result message loop with in-flight guard to prevent
overlapping fetches
- Stderr discarded in watch command execution to avoid corrupting the
TUI
- `ClearCache` on diffviewer for clean re-renders on refresh
- Active watch command shown in footer bar
- README updated with watch mode flags and usage examples

---------

Co-authored-by: Dolev Hadar <dolevc2@gmail.com>

Author: vertti

.github/workflows/build.yml

@@ -0,0 +1,24 @@
+name: build
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: stable
+      - name: test
+        run: |
+          go test -v -failfast -race -coverpkg=./... -covermode=atomic -coverprofile=coverage.txt ./...
+      - uses: codecov/codecov-action@v5
+        if: matrix.os == 'ubuntu-latest'
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          file: ./coverage.txt

.github/workflows/lint.yml

@@ -0,0 +1,20 @@
+name: golangci-lint
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  golangci:
+    name: lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: stable
+      - name: golangci-lint
+        uses: golangci/golangci-lint-action@v9
+        with:
+          version: v2.11.3

README.md

@@ -58,10 +58,13 @@ git config --global pager.diff diffnav
 
 ## Flags
 
-| Flag                 | Description                  |
-| -------------------- | ---------------------------- |
-| `--side-by-side, -s` | Force side-by-side diff view |
-| `--unified, -u`      | Force unified diff view      |
+| Flag                 | Description                                      |
+| -------------------- | ------------------------------------------------ |
+| `--side-by-side, -s` | Force side-by-side diff view                     |
+| `--unified, -u`      | Force unified diff view                          |
+| `--watch, -w`        | Watch mode: periodically re-run a command and refresh |
+| `--watch-cmd`        | Command to run in watch mode (implies `--watch`, default: `git diff`) |
+| `--watch-interval`   | Interval between watch refreshes (default: `2s`) |
 
 Example:
 
@@ -70,6 +73,21 @@ git diff | diffnav --unified
 git diff | diffnav -u
 ```
 
+### Watch Mode
+
+Watch mode lets diffnav periodically re-run a diff command and refresh the display automatically. This is useful for monitoring changes as you work.
+
+```sh
+# watch unstaged changes (default: git diff, every 2s)
+diffnav --watch
+
+# watch staged changes with a custom interval
+diffnav --watch-cmd "git diff --cached" --watch-interval 5s
+
+# watch changes against a specific branch
+diffnav --watch-cmd "git diff main..."
+```
+
 ## Configuration
 
 The config file is searched in this order:

cmd/root.go

@@ -23,6 +23,7 @@ import (
 	"github.com/dlvhdr/diffnav/pkg/config"
 	"github.com/dlvhdr/diffnav/pkg/ui"
 	"github.com/dlvhdr/diffnav/pkg/version"
+	"github.com/dlvhdr/diffnav/pkg/watch"
 )
 
 //go:embed logo-diff-part.txt
@@ -48,6 +49,10 @@ gh pr diff https://github.com/dlvhdr/gh-dash/pull/447 | diffnav
 
 # set up as the global git diff pager
 git config --global pager.diff diffnav
+
+# watch mode: auto-refresh a diff command
+diffnav --watch
+diffnav --watch --watch-cmd "git diff HEAD" --watch-interval 5s
 	`,
 }
 
@@ -79,6 +84,11 @@ func init() {
 
 	rootCmd.Flags().BoolP("unified", "u", false, "Force unified diff view")
 
+	rootCmd.Flags().
+		BoolP("watch", "w", false, "Watch mode: periodically re-run a diff command and refresh")
+	rootCmd.Flags().String("watch-cmd", "git diff", "Command to run in watch mode")
+	rootCmd.Flags().Duration("watch-interval", 2*time.Second, "Interval between watch refreshes")
+
 	rootCmd.SetVersionTemplate("\n" + logo + "\n" + `{{printf "version %s\n" .Version}}`)
 
 	rootCmd.Run = func(cmd *cobra.Command, args []string) {
@@ -97,17 +107,23 @@ func init() {
 			log.Fatal("Cannot parse the help flag", err)
 		}
 
-		zone.NewGlobal()
-
-		stat, err := os.Stdin.Stat()
+		watchFlag, err := cmd.Flags().GetBool("watch")
 		if err != nil {
-			panic(err)
+			log.Fatal("Cannot parse the watch flag", err)
 		}
-
-		if !helpFlag && stat.Mode()&os.ModeNamedPipe == 0 && stat.Size() == 0 {
-			fmt.Println("No diff, exiting")
-			os.Exit(0)
+		watchCmd, err := cmd.Flags().GetString("watch-cmd")
+		if err != nil {
+			log.Fatal("Cannot parse the watch-cmd flag", err)
 		}
+		watchInterval, err := cmd.Flags().GetDuration("watch-interval")
+		if err != nil {
+			log.Fatal("Cannot parse the watch-interval flag", err)
+		}
+		if cmd.Flags().Changed("watch-cmd") {
+			watchFlag = true
+		}
+
+		zone.NewGlobal()
 
 		if os.Getenv("DEBUG") == "true" {
 			var fileErr error
@@ -144,26 +160,50 @@ func init() {
 			log.SetLevel(log.FatalLevel)
 		}
 
-		reader := bufio.NewReader(os.Stdin)
-		var b strings.Builder
+		var input string
+		if watchFlag {
+			stat, sErr := os.Stdin.Stat()
+			if sErr == nil && stat.Mode()&os.ModeNamedPipe != 0 {
+				fmt.Fprintln(os.Stderr, "Warning: stdin input ignored in watch mode")
+			}
+			output, wErr := watch.RunCmd(watchCmd)
+			if wErr != nil {
+				log.Warn("initial watch command failed, starting with empty diff", "err", wErr)
+			}
+			input = output
+		} else {
+			stat, sErr := os.Stdin.Stat()
+			if sErr != nil {
+				panic(sErr)
+			}
+
+			if !helpFlag && stat.Mode()&os.ModeNamedPipe == 0 && stat.Size() == 0 {
+				fmt.Println("No diff, exiting")
+				os.Exit(0)
+			}
 
-		for {
-			r, _, err := reader.ReadRune()
-			if err != nil && err == io.EOF {
-				break
+			reader := bufio.NewReader(os.Stdin)
+			var b strings.Builder
+
+			for {
+				r, _, rErr := reader.ReadRune()
+				if rErr != nil && rErr == io.EOF {
+					break
+				}
+				_, rErr = b.WriteRune(r)
+				if rErr != nil {
+					fmt.Println("Error getting input:", rErr)
+					os.Exit(1)
+				}
 			}
-			_, err = b.WriteRune(r)
-			if err != nil {
-				fmt.Println("Error getting input:", err)
-				os.Exit(1)
+
+			input = ansi.Strip(b.String())
+			if strings.TrimSpace(input) == "" {
+				fmt.Println("No input provided, exiting")
+				os.Exit(0)
 			}
 		}
 
-		input := ansi.Strip(b.String())
-		if strings.TrimSpace(input) == "" {
-			fmt.Println("No input provided, exiting")
-			os.Exit(0)
-		}
 		cfg := config.Load()
 
 		// Override config with CLI flags if specified
@@ -173,6 +213,12 @@ func init() {
 			cfg.UI.SideBySide = true
 		}
 
+		cfg.Watch = config.WatchConfig{
+			Enabled:  watchFlag,
+			Cmd:      watchCmd,
+			Interval: watchInterval,
+		}
+
 		ttyIn, _, err := tea.OpenTTY()
 		if err != nil {
 			log.Fatal(err)

devbox.json

@@ -1,12 +1,12 @@
 {
   "$schema": "https://raw.githubusercontent.com/jetify-com/devbox/0.14.0/.schema/devbox.schema.json",
   "packages": {
-    "go":            "1.22.6",
-    "gopls":         "latest",
-    "golangci-lint": "latest",
-    "svu":           "latest",
-    "git":           "latest",
-    "go-task":       "latest"
+    "go": "1.22.6",
+    "gopls": "latest",
+    "golangci-lint": "2.11.3",
+    "svu": "latest",
+    "git": "latest",
+    "go-task": "latest"
   },
   "shell": {
     "scripts": {

devbox.lock

@@ -172,51 +172,51 @@
         }
       }
     },
-    "golangci-lint@latest": {
-      "last_modified": "2025-03-25T17:32:05Z",
-      "resolved": "github:NixOS/nixpkgs/25d1b84f5c90632a623c48d83a2faf156451e6b1#golangci-lint",
+    "golangci-lint@2.11.3": {
+      "last_modified": "2026-03-11T04:01:32Z",
+      "resolved": "github:NixOS/nixpkgs/b6067cc0127d4db9c26c79e4de0513e58d0c40c9#golangci-lint",
       "source": "devbox-search",
-      "version": "2.0.0",
+      "version": "2.11.3",
       "systems": {
         "aarch64-darwin": {
           "outputs": [
             {
               "name": "out",
-              "path": "/nix/store/idv9cyl4i6w9n4sgc29kvqhywm04n1rz-golangci-lint-2.0.0",
+              "path": "/nix/store/zalxgqwyng4jdbv5cpsmm9xbmim9hjjj-golangci-lint-2.11.3",
               "default": true
             }
           ],
-          "store_path": "/nix/store/idv9cyl4i6w9n4sgc29kvqhywm04n1rz-golangci-lint-2.0.0"
+          "store_path": "/nix/store/zalxgqwyng4jdbv5cpsmm9xbmim9hjjj-golangci-lint-2.11.3"
         },
         "aarch64-linux": {
           "outputs": [
             {
               "name": "out",
-              "path": "/nix/store/r0jxwvqvk2999dx04v3j9jgd46jscqc4-golangci-lint-2.0.0",
+              "path": "/nix/store/mbra9idrmw8f8a4sqv2d0bf6vw8gcmfp-golangci-lint-2.11.3",
               "default": true
             }
           ],
-          "store_path": "/nix/store/r0jxwvqvk2999dx04v3j9jgd46jscqc4-golangci-lint-2.0.0"
+          "store_path": "/nix/store/mbra9idrmw8f8a4sqv2d0bf6vw8gcmfp-golangci-lint-2.11.3"
         },
         "x86_64-darwin": {
           "outputs": [
             {
               "name": "out",
-              "path": "/nix/store/lsyy8arab3zvkpi8lr9303mf88y5k1rc-golangci-lint-2.0.0",
+              "path": "/nix/store/ph64c01zwvbr9xvxydxa8ijvbdfax8fy-golangci-lint-2.11.3",
               "default": true
             }
           ],
-          "store_path": "/nix/store/lsyy8arab3zvkpi8lr9303mf88y5k1rc-golangci-lint-2.0.0"
+          "store_path": "/nix/store/ph64c01zwvbr9xvxydxa8ijvbdfax8fy-golangci-lint-2.11.3"
         },
         "x86_64-linux": {
           "outputs": [
             {
               "name": "out",
-              "path": "/nix/store/834gvbmhpwvy1d65r5x4xihkxm4g91ab-golangci-lint-2.0.0",
+              "path": "/nix/store/i1xcg5f24w70llk4v6lzi0vi4jf3ma5k-golangci-lint-2.11.3",
               "default": true
             }
           ],
-          "store_path": "/nix/store/834gvbmhpwvy1d65r5x4xihkxm4g91ab-golangci-lint-2.0.0"
+          "store_path": "/nix/store/i1xcg5f24w70llk4v6lzi0vi4jf3ma5k-golangci-lint-2.11.3"
         }
       }
     },

mise.toml

@@ -0,0 +1,2 @@
+[tools]
+go = "1.24.11"

pkg/config/config.go

@@ -4,6 +4,7 @@ import (
 	"os"
 	"path/filepath"
 	"runtime"
+	"time"
 
 	"gopkg.in/yaml.v3"
 )
@@ -20,8 +21,15 @@ type UIConfig struct {
 	SideBySide      bool   `yaml:"sideBySide"`     // Side-by-side diff view (default: true)
 }
 
+type WatchConfig struct {
+	Enabled  bool
+	Cmd      string
+	Interval time.Duration
+}
+
 type Config struct {
-	UI UIConfig `yaml:"ui"`
+	UI    UIConfig    `yaml:"ui"`
+	Watch WatchConfig `yaml:"-"`
 }
 
 func DefaultConfig() Config {

pkg/ui/panes/diffviewer/diffviewer.go

@@ -113,7 +113,7 @@ func (m *Model) SetSize(width, height int) tea.Cmd {
 	m.Height = height
 	m.vp.SetWidth(m.contentWidth())
 	m.vp.SetHeight(m.Height - dirHeaderHeight)
-	m.cache = make(nodeCache)
+	m.ClearCache()
 	return m.diff()
 }
 
@@ -368,7 +368,10 @@ func renderPreamble(preamble string) string {
 	for _, line := range strings.Split(preamble, "\n") {
 		switch {
 		case strings.HasPrefix(line, "commit "):
-			out = append(out, dim.Render("commit ")+yellow.Render(strings.TrimPrefix(line, "commit ")))
+			out = append(
+				out,
+				dim.Render("commit ")+yellow.Render(strings.TrimPrefix(line, "commit ")),
+			)
 		case strings.HasPrefix(line, "Author:"),
 			strings.HasPrefix(line, "AuthorDate:"),
 			strings.HasPrefix(line, "Date:"),
@@ -389,6 +392,10 @@ type diffContentMsg struct {
 	text     string
 }
 
+func (m *Model) ClearCache() {
+	m.cache = make(nodeCache)
+}
+
 func (m *Model) RootDiffStats() (int64, int64) {
 	if item, ok := m.cache[cacheKey("/", m.sideBySide)]; ok {
 		return item.additions, item.deletions

pkg/ui/panes/filetree/filetree.go

@@ -312,7 +312,6 @@ func collapseTree(t *tree.Node) *tree.Node {
 		child := newChildren[0]
 		// If the child is dir with one chlid that's also a dir -> collapse it
 		if dir, ok := child.GivenValue().(*dirnode.DirNode); ok {
-
 			// if the only child is a tree and its parent is the root we don't want to collapse.
 			// The root should always be visible
 			if rootDir.Name == constants.RootName {