0
# File Watching
1

2
Core filesystem monitoring operations for establishing watches, listing watched directories, and removing watches. These commands form the foundation of Watchman's file monitoring capabilities.
3

4
## Capabilities
5

6
### Watch Directory
7

8
Establishes monitoring for a directory tree, causing Watchman to track all files and subdirectories for changes.
9

10
```bash { .api }
11
watchman watch <path>
12
```
13

14
**JSON Protocol:**
15
```json
16
["watch", "/absolute/path/to/directory"]
17
```
18

19
**Parameters:**
20
- `path`: Absolute path to directory to watch (required)
21

22
**Response:**
23
```json
24
{
25
  "version": "2.0",
26
  "watch": "/absolute/path/to/directory"
27
}
28
```
29

30
When a directory is first watched, Watchman:
31
1. Establishes change notification with the kernel (inotify/kqueue/port_create)
32
2. Queues a request to crawl the directory tree
33
3. Processes subdirectories recursively
34
4. Considers all newly observed files as changed
35

36
**Example:**
37
```bash
38
# Watch a project directory
39
watchman watch ~/my-project
40

41
# Watch using absolute path
42
watchman watch /home/user/code/project
43
```
44

45
### List Watched Directories
46

47
Returns a list of all directories currently being watched by the Watchman daemon.
48

49
```bash { .api }
50
watchman watch-list
51
```
52

53
**JSON Protocol:**
54
```json
55
["watch-list"]
56
```
57

58
**Response:**
59
```json
60
{
61
  "version": "2.0", 
62
  "roots": [
63
    "/home/user/project1",
64
    "/home/user/project2"
65
  ]
66
}
67
```
68

69
**Example:**
70
```bash
71
$ watchman watch-list
72
{
73
    "version": "2.0",
74
    "roots": [
75
        "/home/user/my-project"
76
    ]
77
}
78
```
79

80
### Remove Watch
81

82
Stops watching a directory and removes it from the active watch list.
83

84
```bash { .api }
85
watchman watch-del <path>
86
```
87

88
**JSON Protocol:**
89
```json
90
["watch-del", "/absolute/path/to/directory"]
91
```
92

93
**Parameters:**
94
- `path`: Absolute path to directory to stop watching (required)
95

96
**Response:**
97
```json
98
{
99
  "version": "2.0",
100
  "watch-del": true,
101
  "root": "/absolute/path/to/directory"
102
}
103
```
104

105
The removed watch is also removed from the state file and will not be automatically restored if Watchman restarts.
106

107
**Example:**
108
```bash
109
# Stop watching a directory
110
watchman watch-del ~/my-project
111
```
112

113
### Get Clock Value
114

115
Returns the current clock value for a watched directory. The clock represents Watchman's internal notion of time for that watch.
116

117
```bash { .api }
118
watchman clock <path>
119
```
120

121
**JSON Protocol:**
122
```json
123
["clock", "/absolute/path/to/directory"]
124
```
125

126
**Parameters:**
127
- `path`: Absolute path to watched directory (required)
128

129
**Response:**
130
```json
131
{
132
  "version": "2.0",
133
  "clock": "c:1234:567"
134
}
135
```
136

137
**Clock Format:**
138
- Format: `c:TICKS:PID` where TICKS is an incrementing counter and PID is the process ID
139
- Used for race-free change detection in subsequent queries
140
- More reliable than Unix timestamps for file change tracking
141

142
**Example:**
143
```bash
144
$ watchman clock ~/my-project
145
{
146
    "version": "2.0",
147
    "clock": "c:1234:567"
148
}
149
```
150

151
## Watch State Management
152

153
Watchman persists watch information in a state file to maintain watches across service restarts:
154

155
- **Default state file**: `$TMPDIR/.watchman.$USER.state` 
156
- **Custom state file**: Use `--statefile=PATH` option
157
- **Disable state**: Use `-n` or `--no-save-state` option
158

159
## System Requirements
160

161
### Linux (inotify)
162
- Requires `inotify` kernel support
163
- Check system limits: `/proc/sys/fs/inotify/max_user_watches`
164
- May need to increase limits for large directory trees
165

166
### macOS/BSD (kqueue)  
167
- Requires `kqueue(2)` facility
168
- Each watched file consumes a file descriptor
169
- May need to increase file descriptor limits
170

171
### Solaris (port_create)
172
- Requires `port_create(3C)` facility
173
- Available on Illumos and Solaris systems
174

175
## Error Handling
176

177
Common error conditions:
178

179
- **Directory not found**: Path does not exist or is not accessible
180
- **Not a directory**: Path refers to a file, not a directory  
181
- **Permission denied**: Insufficient permissions to read directory
182
- **Already watching**: Directory is already being watched
183
- **System limits**: Exceeded inotify watches or file descriptor limits