Registering Repositories¶

Learn how to register, manage, and unregister repositories with Gity.

Basic Registration¶

Register a repository to start accelerating Git operations:

gity register /path/to/repo

Or from within the repository:

cd /path/to/repo
gity register .

What Registration Does¶

When you register a repository, Gity:

Starts a file watcher — Monitors the working tree for changes using OS-native APIs
Configures Git — Sets up fsmonitor and related optimizations in .git/config
Performs initial scan — Caches the current file state for fast comparisons
Schedules maintenance — Queues background tasks like prefetch and commit-graph updates

Git Configuration Changes¶

Registration adds these settings to your repository's .git/config:

[core]
    fsmonitor = gity fsmonitor-helper
    untrackedCache = true

[feature]
    manyFiles = true

These are automatically removed when you unregister.

Managing Multiple Repositories¶

Listing Registered Repos¶

gity list

Output (one repo per line, with queue depth, status, and watcher generation):

/home/user/projects/frontend [0 jobs, status idle, gen 12]
/home/user/projects/backend  [1 jobs, status busy, gen 47]
/home/user/work/monorepo     [0 jobs, status idle, gen 5]

With Statistics¶

gity list --stats

--stats augments each repo line with daemon-side resource numbers (CPU %, RSS, cache size, queued jobs). The exact column layout is driven by the daemon's metrics output — see gity daemon metrics for the underlying data.

Worktrees¶

Git worktrees are separate working directories that share the same .git object store. Register each worktree independently:

# Main worktree
gity register /path/to/repo

# Feature worktree
gity register /path/to/repo-feature-x

# Another worktree
gity register /path/to/repo-bugfix-y

Benefits:

Each worktree has its own file watcher
Cache data is shared when possible (via rykv replication)
Independent health tracking

Unregistering¶

Stop accelerating a repository:

gity unregister /path/to/repo

This:

Stops the file watcher
Removes Gity-specific Git configuration
Cleans up cached metadata

Always unregister before deleting

If you delete a repository directory without unregistering, run gity list and manually unregister any stale entries.

Repository Health¶

Check the health of a registered repository:

gity health /path/to/repo

Output includes:

Watcher status (active, reconciling, error)
Current generation token
Dirty path count
Scheduled jobs
Resource usage

Troubleshooting Registration¶

Repository Not Found¶

Error: Repository not found at /path/to/repo

Ensure the path points to a valid Git repository (contains .git).

Already Registered¶

Warning: Repository already registered

The repository is already being watched. Use gity health to check its status.

Permission Denied¶

Error: Permission denied accessing /path/to/repo

Ensure you have read/write access to the repository and its .git directory.

Watcher Limits¶

On Linux, you may hit inotify watch limits. See Linux Platform Guide for solutions.

Best Practices¶

Register at the root — Always register the repository root, not subdirectories
One registration per worktree — Each worktree needs its own registration
Avoid network filesystems — File watching is unreliable on NFS, SMB, SSHFS
WSL2 users — Keep repos on the Linux filesystem, not /mnt/c/. See WSL2 Guide
Clean up stale registrations — Run gity list periodically and unregister deleted repos