Configuration and tuning

pgit has two layers of configuration: per-repository settings (who you are, your remotes) and global settings (the database container and import defaults, shared by every repo). The default container settings are deliberately conservative, sized for an 8 GB laptop, so the main reason to tune is to make large imports and queries faster on a bigger machine.

The two scopes

• Repository config lives in .pgit/config.toml inside each repo. It holds your commit identity and remotes.
• Global config lives in your user config directory and applies everywhere: ~/.config/pgit/config.toml on Linux (or $XDG_CONFIG_HOME/pgit), ~/Library/Application Support/pgit/config.toml on macOS, and %APPDATA%\pgit\config.toml on Windows.

You rarely edit these files by hand. Use the config command.

The config command

pgit config user.name "Ada Lovelace"   # set a repo valuepgit config user.name                  # get a repo valuepgit config --list                     # list repo configpgit config --global --list                       # list global configpgit config --global container.shared_buffers 2GB # set a global valuepgit config --global container.shared_buffers     # get a global value

Values are validated when you set them, so an out-of-range port or a malformed size is rejected rather than silently breaking the container.

Repository settings

If user.name or user.email is unset, pgit falls back to the PGIT_AUTHOR_NAME / PGIT_AUTHOR_EMAIL environment variables, then to your git config. You can also set a global default identity with pgit config --global user.name "...".

Global settings and the restart rule

Global config covers the PostgreSQL container (container.*) and the import default (import.workers). The container reads these once, at startup.

pgit local destroy && pgit local start

Environment variables

A handful of variables tweak behaviour without touching config files:

Tuning for your hardware

The defaults suit a small machine. If you are importing or querying a large repository, pick the profile closest to your hardware and paste it, then restart the container. These are starting points, not gospel; measure and adjust.

pgit config --global container.shared_buffers 2GBpgit config --global container.effective_cache_size 6GBpgit config --global container.shm_size 3gpgit config --global container.work_mem 32MBpgit config --global container.max_wal_size 4GBpgit config --global container.max_worker_processes 8pgit config --global container.max_parallel_workers 4pgit config --global container.xpatch_cache_size_mb 1024pgit config --global container.xpatch_encode_threads 4pgit config --global import.workers 4

pgit config --global container.shared_buffers 16GBpgit config --global container.effective_cache_size 48GBpgit config --global container.shm_size 20gpgit config --global container.work_mem 128MBpgit config --global container.max_wal_size 8GBpgit config --global container.max_worker_processes 12pgit config --global container.max_parallel_workers 8pgit config --global container.xpatch_cache_size_mb 8192pgit config --global container.xpatch_encode_threads 8pgit config --global import.workers 8

pgit config --global container.shared_buffers 64GBpgit config --global container.effective_cache_size 200GBpgit config --global container.shm_size 80gpgit config --global container.work_mem 256MBpgit config --global container.max_wal_size 32GBpgit config --global container.max_worker_processes 20pgit config --global container.max_parallel_workers 16pgit config --global container.xpatch_cache_size_mb 32768pgit config --global container.xpatch_encode_threads 16pgit config --global import.workers 16

Then apply:

pgit local destroy && pgit local start

Monitoring what you changed

Check whether the cache is doing its job:

pgit sql "SELECT * FROM xpatch.cache_stats()"   # cache hit rate (aim above 90%)pgit stats --xpatch                             # per-table compression and cache detail

• A high miss_count versus hit_count means the cache is too small. Raise xpatch_cache_size_mb.
• A high skip_count means entries are rejected for being too large. Raise xpatch_cache_max_entry_kb.

When something is slow or breaks

• Container will not start (shared memory error): raise shm_size above shared_buffers.
• Import is slow: raise xpatch_encode_threads and import.workers toward your core count, and raise max_wal_size / checkpoint_timeout to cut checkpoint stalls.
• Queries are slow: raise xpatch_cache_size_mb, then re-check cache_stats().
• Out of memory during import: lower import.workers, xpatch_encode_threads, and work_mem.

Setting reference

PostgreSQL settings:

pg-xpatch settings:

Import setting:

For the meaning of each xpatch knob and the engine-side detail, see pg-xpatch server parameters and tuning compression.

Where to go next