watch

The watch command monitors your workspace for source file changes and automatically updates BUILD files when changes are detected. This provides a seamless development experience where BUILD files stay in sync with your code.

Usage

bazelle watch [flags] [path]

Flags

Flag	Description
`--debounce`	Debounce window in milliseconds (default: 500)
`--languages`	Only watch specific languages (comma-separated)
`--verbose`	Show file-level changes
`--json`	Stream JSON events (for tooling integration)
`--no-color`	Disable colored output

Examples

Basic Watch

Start watching the current workspace:

bazelle watch

Example output:

bazelle: watching 1,247 files in /path/to/workspace
bazelle: languages: go, kotlin, python
bazelle: ready

[14:32:15] ~ src/auth/login.kt
[14:32:15] updating //src/auth:all...
[14:32:16] ✓ src/auth/BUILD.bazel updated

[14:35:42] + src/api/handler.go
[14:35:42] updating //src/api:all...
[14:35:43] ✓ src/api/BUILD.bazel updated

Press Ctrl+C to stop watching.

Watch Specific Directory

Watch only a subdirectory:

bazelle watch ./src

Filter Languages

Only watch specific languages:

bazelle watch --languages go,kotlin

Verbose Mode

Show detailed file-level changes:

bazelle watch --verbose

JSON Output

For integration with editors and tools:

bazelle watch --json

Example JSON events:

{"type":"ready","files":1247,"languages":["go","kotlin","python"]}
{"type":"change","file":"src/auth/login.kt","action":"modified"}
{"type":"update","target":"//src/auth:all","status":"started"}
{"type":"update","target":"//src/auth:all","status":"completed","file":"src/auth/BUILD.bazel"}

Debounce Configuration

Adjust the debounce window (useful for slow file systems or rapid edits):

# Longer debounce for slower systems
bazelle watch --debounce 1000

# Shorter debounce for faster feedback
bazelle watch --debounce 200

How It Works

Startup: Scans the workspace and registers file watchers for source files
Detection: Uses OS file system events (fsnotify) to detect changes
Debouncing: Groups rapid changes within the debounce window
Update: Runs Gazelle on affected directories
Output: Reports which BUILD files were updated

Ignored Files

Watch automatically ignores:

.git/ directory
bazel-* directories (Bazel output)
.bazelle/ state directory
Files matching .gitignore patterns
Binary files and build artifacts

Integration with Editors

VS Code with Daemon (Recommended)

For the best experience, use the daemon mode:

Start the daemon: bazelle daemon start
In VS Code, run “Bazelle: Start Watch Mode”
The extension connects to the daemon automatically

Benefits of daemon mode:

Zero startup overhead
Shared file watcher across clients
Survives VS Code restarts

See VS Code Extension for full documentation.

VS Code with Tasks

If you prefer tasks.json:

{
  "label": "Bazelle Watch",
  "type": "shell",
  "command": "bazelle watch --json",
  "isBackground": true,
  "problemMatcher": []
}

Terminal Multiplexer

Run watch in a split pane while developing:

# tmux example
tmux split-window -h 'bazelle watch'

Daemon vs Standalone Watch

The bazelle watch command can run:

Standalone: Directly as a foreground process
Via Daemon: As part of the background daemon

Mode	Command	Use Case
Standalone	`bazelle watch`	Quick testing, simple workflows
Daemon	`bazelle daemon start` + connect	Development with VS Code, multiple tools

Graceful Shutdown

Watch handles signals gracefully:

Ctrl+C (SIGINT): Clean shutdown
SIGTERM: Clean shutdown
SIGHUP: Clean shutdown (terminal closed)

Performance

Watch is optimized for large codebases:

Only processes directories with actual changes
Uses efficient file system watching (fsnotify)
Debounces rapid changes to avoid redundant updates
Filters irrelevant files at the OS level

Limitations

Does not track changes made by external tools that bypass file system events
Some network file systems may not support file watching
Very large workspaces (100k+ files) may need increased debounce times