funk-auto-sync

A lightweight, cross-platform tool that automatically syncs one or more Git repositories on every local file change. Written in Go as a single static binary with an embedded dark-monochrome Web UI dashboard, native OS file pickers, and zero external runtime dependencies.

Designed for note-taking vaults (Obsidian, Logseq, Foam, plain Markdown), office documents (.docx, .xlsx), and personal config folders where you want continuous, hands-off backup to remote Git repositories without having to touch the command line.

 edit file → detected → gitignore & lock-file check → debounce → add (exclude secrets) → scan staged → commit → pull --rebase (retry) → push (retry) → live streamed & notified

Table of contents

• Features
• Web UI Dashboard
• Requirements
• Quick start
• Installation
• Usage & Flags
• How it works
• Watching multiple folders
• Office & Binary file support
• Handling conflicts
• Running as a background service
• Reducing binary size
• Development & Tests
• Project structure
• License

Features

Feature	Description
Embedded Web Dashboard	Single-page modern dark-monochrome web UI (http://localhost:8989) served directly from the binary via Go embed. Zero npm/NodeJS dependencies.
Password Authentication	Session-based login with HMAC tokens in HTTP-only cookies and in-dashboard password management.
Cross-Platform Browsing	Add folders via native OS pickers (PowerShell on Windows, AppleScript on macOS, Zenity/KDialog on Linux) or the built-in Web Directory Explorer.
Dynamic Repository Management	Add and remove watched Git repositories on the fly from the UI without restarting the binary.
Live SSE Terminal	Real-time log streaming using Server-Sent Events (SSE) directly in the web dashboard.
Multi-folder watching	Watch any number of independent Git repositories in a single process.
Recursive watching	Automatically discovers and watches all subdirectories on startup and registers newly created ones at runtime.
Debounce per repo	Rapid successive edits collapse into a single commit once the cooldown window passes (-debounce, default 2s).
Descriptive commit messages	Generates human-readable commit messages from the staged diff (e.g. Update notes.md (+12/-3); Add todo.md (+5) — 2026-08-31 10:15:00).
Binary file friendly	Handles binary files like .docx, .xlsx, .pdf, and images cleanly with descriptive (binary) commit summaries.
Office lock-file filtering	Automatically ignores temporary lock files created by Word and Excel (~$*.docx, ~$*.xlsx) to prevent sync noise.
Gitignore aware	Uses git check-ignore so repository-level and global ignore rules are respected without reimplementing them.
Secret protection	Appends :(exclude) pathspecs for sensitive patterns (.env*, *.pem, *.key, credentials) on git add, plus secondary staged content scanning.
Push/Pull retry	Automatically retries transient network failures on git pull --rebase and git push with exponential backoff (1s, 2s, 4s).
Safe rebase on conflict	If git pull --rebase runs into a merge conflict, it automatically runs git rebase --abort to keep the local repo clean, preserving your commit.
Desktop notifications	Cross-platform notifications on success, conflicts, and errors via native system notifications.

Web UI Dashboard

By default, launching funk-auto-sync starts the embedded HTTP server and automatically opens your browser at:

http://localhost:8989

• Default credentials: Password is admin. A prominent banner will prompt you to change it on first login.
• Controls:
  • Live / Paused Toggle: Pause watcher during heavy editing sessions or resume with one click.
  • Sync All / Sync Now: Manually trigger immediate sync for one or all repositories.
  • Add Repository: Select folders using the native OS file picker (Browse...) or use the built-in directory explorer (Explorer).
  • Live Terminal: Monospace streaming terminal showing real-time Git actions and status.
  • Settings Modal: Update your dashboard password and adjust sync debounce seconds.

Requirements

• Go 1.21 or newer (to build from source)
• Git installed and available on your PATH
• A configured Git repository with an origin remote for every folder you want to watch

Quick start

# Clone the repository
git clone https://github.com/funk71on/funk-auto-sync.git
cd funk-auto-sync

# Build the binary
go build -o funk-auto-sync .

# Run (opens web dashboard automatically)
./funk-auto-sync

On Windows, simply double-click funk-auto-sync.exe in File Explorer.

Installation

From source

git clone https://github.com/funk71on/funk-auto-sync.git
cd funk-auto-sync
go build -o funk-auto-sync .

The compiled binary will be placed at ./funk-auto-sync (or funk-auto-sync.exe on Windows).

To install it directly into your $GOPATH/bin:

go install .

Usage & Flags

# Start with Web UI (default, auto-opens browser)
./funk-auto-sync

# Specify custom web port
./funk-auto-sync -port 9090

# Start without opening browser window automatically
./funk-auto-sync -no-browser

# Headless pure CLI mode (no web server)
./funk-auto-sync -cli -path /path/to/notes

# Watch multiple directories directly via CLI
./funk-auto-sync -path /path/to/notes -path /path/to/journal

# Adjust debounce window (supports ms, s, m)
./funk-auto-sync -debounce 5s

# Check version
./funk-auto-sync -version

# Show help
./funk-auto-sync -help

Available flags

Flag	Type	Default	Description
-port	int	8989	Port for the Web UI dashboard (overrides saved config).
-cli	bool	false	Run in headless CLI mode without starting the Web UI server.
-no-browser	bool	false	Do not automatically launch the web browser on startup.
-path	string	.	Initial path(s) to watch. Repeatable (-path a -path b) or comma-separated (-path a,b).
-debounce	duration	2s	How long to wait for changes to settle before syncing.
-version	bool	false	Print the version number and exit.

How it works

When funk-auto-sync starts:

1. Config initialization: Loads or creates funk-sync.json containing saved watch paths, debounce delay, and hashed credentials.
2. Pre-flight validation: Checks that git is on your PATH and verifies each watched path is an existing Git repository with an origin remote.
3. Recursive watcher: Recursively registers all subdirectories with fsnotify. Any new folders created later are picked up automatically.
4. Event filtering: Temporary editor swap files (*~, .*), office lock files (~$*), and files matched by .gitignore are immediately skipped.
5. Per-repo debounce: Waits for the debounce duration without new changes in that repository before triggering the pipeline.
6. Git Add with secret exclude: Runs git add . with :(exclude) pathspecs for sensitive files (.env, *.key, *.pem, etc.).
7. Staged content scan: Inspects staged files for credentials/private keys. If found, resets staging and aborts for safety.
8. Descriptive commit: Generates a commit message summarizing changed files and line additions/deletions (e.g. Update notes.md (+12/-3); Add report.docx (binary) — 2026-08-31 10:15:00).
9. Pull with rebase & retry: Executes git pull origin <branch> --rebase with exponential backoff retries.
10. Push with retry: Executes git push origin <branch> with exponential backoff retries.
11. Live broadcast & notification: Streams output to all connected dashboard SSE clients and fires native desktop alerts.

Office & Binary file support

funk-auto-sync works seamlessly with binary documents (such as .docx, .xlsx, .pptx, .pdf, and images):

• Lock-file exclusion: Word and Excel create temporary lock files (e.g. ~$Annual_Report.docx) during editing. These files are filtered out automatically to avoid commit noise and race conditions.
• Commit formatting: Since binary files do not have line diffs, they are formatted as Update Annual_Report.docx (binary) instead of misleading (+0/-0).
• Debounce tip for large files: Saving large Office documents involves writing temporary files before renaming. If commits trigger prematurely during large saves, increase the debounce delay via UI settings or CLI flag:

  ./funk-auto-sync -debounce 5s

Watching multiple folders

A single process can watch several independent Git repositories at once — each keeps its own branch, remote, and commit history. You can manage them directly inside the Web Dashboard or supply them via CLI:

./funk-auto-sync -path ~/notes -path ~/journal -path ~/dotfiles

Handling conflicts

Design philosophy: No silent overwrites

Automated background sync tools must never perform blind conflict resolution (such as --strategy-option=ours or theirs). Forcing an auto-merge risks silent data loss, particularly with binary documents (.docx, .xlsx) and structured notes where three-way text merges can silently clobber content without the user realizing it.

Current behavior (Safe abort)

When git pull --rebase encounters conflicts against remote changes:

1. Immediate abort: Automatically executes git rebase --abort to return the working tree cleanly to your local commit without leaving unresolved <<<<<<< conflict markers.
2. Notification & Log: Dispatches a desktop alert (Git CONFLICT!) and logs details of the conflicting branch and file.
3. Preservation: Your local work remains safely committed in your local repository history so no keystrokes are lost.

Running as a background service (optional)

Linux (systemd user service)

Create ~/.config/systemd/user/funk-auto-sync.service:

[Unit]
Description=Funk Auto Sync

[Service]
ExecStart=/absolute/path/to/funk-auto-sync -no-browser
Restart=on-failure

[Install]
WantedBy=default.target

Enable and start:

systemctl --user enable --now funk-auto-sync.service

macOS (launchd)

Create ~/Library/LaunchAgents/com.funk.funk-auto-sync.plist pointing to the compiled binary with -no-browser, then load it:

launchctl load ~/Library/LaunchAgents/com.funk.funk-auto-sync.plist

Windows (Startup / Task Scheduler)

Create a shortcut to funk-auto-sync.exe in your shell:startup folder or use Task Scheduler to launch at logon.

Reducing binary size

Build a stripped, fully static binary without CGO:

# Linux / macOS
CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o funk-auto-sync .

# Windows (PowerShell)
$env:CGO_ENABLED=0; go build -trimpath -ldflags="-s -w" -o funk-auto-sync.exe .

Development & Tests

Run the complete unit test suite:

go test ./... -v

Project structure

.
├── main.go        # Entry point, flag parsing, and startup orchestration
├── server.go      # Embedded HTTP server, routes, and OS folder dialog
├── manager.go     # Dynamic sync engine, log ring-buffer, and SSE stream
├── config.go      # JSON configuration persistence and password hashing
├── auth.go        # Authentication, HMAC sessions, and password change
├── web/           # Embedded web frontend assets (HTML, CSS, JS)
│   └── index.html # Dark monochrome single-page dashboard
├── auth_test.go   # Authentication and session unit tests
├── config_test.go # Configuration manager unit tests
├── main_test.go   # Git sync pipeline and watcher unit tests
├── go.mod         # Go module definition
├── .gitignore     # Git ignore rules (ignores funk-sync.json, logs, binaries)
└── README.md      # Documentation

License

MIT — feel free to use, modify, and distribute.