Add README with usage, flags, and .gitignore support docs

1 files changed, 70 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ae616d2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,70 @@
+# sourcewatch
+
+A file synchronization tool that watches a source directory and syncs changes to a destination, respecting `.gitignore` rules. Designed to run in Docker on Windows with a read-only bind mount.
+
+## How it works
+
+1. **Initial sync** — copies all non-ignored files from `/host` to `/data`
+2. **Watch** — monitors `/host` for changes and syncs them in real-time
+
+## Usage
+
+```bash
+# Linux
+docker run -v /path/to/source:/host:ro -v watchdata:/data sourcewatch
+
+# Windows
+docker run -v c:\source:/host:ro -v watchdata:/data sourcewatch
+```
+
+## Flags
+
+```
+-host string      Host source directory (default "/host")
+-data string      Data destination directory (default "/data")
+-verbose          Enable verbose logging
+-dry-run          Preview what would be synced without copying
+```
+
+## Example
+
+```bash
+# Build
+docker build -t sourcewatch .
+
+# Run with verbose output
+docker run -d --name watch \
+  -v c:\myproject:/host:ro \
+  -v project-data:/data \
+  sourcewatch -verbose
+
+# Check logs
+docker logs -f watch
+
+# Stop
+docker rm -f watch
+```
+
+## .gitignore support
+
+- Full gitignore spec: `*`, `**`, `[]`, `!` negation
+- Nested `.gitignore` files (child patterns override parents)
+- Patterns scoped to their directory
+- `.git` directory always skipped
+
+Example `.gitignore`:
+```
+*.log
+build/
+!important.log
+```
+
+## Limitations
+
+- One-way sync only (`/host` → `/data`)
+- `/host` must be read-only
+- `?` single-character wildcard not supported (go-gitignore limitation)
+
+## License
+
+MIT