Rootbeer

Managing your system

git ​

The git module manages your global Git config from Lua. It writes ~/.gitconfig, can manage a global gitignore, and gives common settings like signing and Git LFS first-class fields.

lua
local git = require("rootbeer.git")

Configure Git ​

Most config maps directly to familiar Git settings. Use extra for tool-specific sections that Rootbeer doesn't model directly, such as delta.

lua
git.config({
    user = {
        name = "Aarnav Tale",
        email = "aarnav@tale.me",
    },
    editor = "nvim",
    pager = "delta",
    signing = { key = "ssh-ed25519 AAAA..." },
    lfs = true,
    pull_rebase = true,
    ignores = { ".DS_Store", "._*", "*~" },
    extra = {
        delta = { features = "color-only" },
    },
})

For different emails, signing keys, or ignores per machine, use Profiles.

Verifying your own signatures ​

Setting signing.key makes Git create signatures, but Git can't verify them without an allowed signers file — git log --show-signature reports No signature on your own commits. List the principals your key signs for and Rootbeer writes the file and wires gpg.ssh.allowedSignersFile to it:

lua
signing = {
    key = "ssh-ed25519 AAAA...",
    allowed_signers = { "aarnav@tale.me", "aarnav@work.example" },
},

Listing every identity you commit under, rather than just this machine's, means commits made on one machine still verify on the others. This applies to SSH signing only; it is skipped for other format values.

Extending built-in sections ​

extra merges into the sections the shortcuts above already wrote, so you can add to [core] or [tag] without losing what Rootbeer put there:

lua
git.config({
    user = { name = "Aarnav Tale", email = "aarnav@tale.me" },
    editor = "nvim",
    ignores = { ".DS_Store" },
    extra = {
        -- Keeps core.editor and core.excludesfile.
        core = { fsmonitor = true, untrackedCache = true },
        rerere = { enabled = true, autoUpdate = true },
        fetch = { prune = true, pruneTags = true },
    },
})

On a key conflict extra wins, which makes it the escape hatch when a shortcut picks a value you disagree with.

API Reference ​

git.config(cfg) ​

Applies git.Config to the system. Writes a gitconfig file at cfg.path and optionally a gitignore file next to it.

Parameters — cfg: git.Config

editorstringoptional
Default editor for commits (e.g. "nvim").
extratable<string, table<string, boolean|string>>optional
Additional gitconfig sections (e.g. delta, interactive). Merges into sections the other fields already wrote rather than replacing them, so extra.core keeps excludesfile. On a key conflict, extra wins.
ignoresstring[]optional
Global gitignore patterns. Written next to the gitconfig.
ignores_pathstringoptional
Override path for the gitignore file. Defaults to .gitignore next to the gitconfig.
lfsbooleanoptional
Enable git-lfs filters (filter.lfs section).
merge_conflictstylestringoptional
Merge conflict style (e.g. "diff3").
pagerstringoptional
Default pager for output (e.g. "delta").
pathstringoptional
Where to write the gitconfig file. Defaults to "~/.gitconfig".
pull_rebasebooleanoptional
Pull with rebase instead of merge.
signinggit.SigningConfigoptional
Commit and tag signing. Sets user.signingkey, gpg.format, commit.gpgSign, and tag.gpgSign.
usergit.UserConfig
User identity.

git.SigningConfig ​

allowed_signersstring[]optional
Principals (usually emails) that key signs for. Writes an allowed signers file and points gpg.ssh.allowedSignersFile at it, which is what lets Git *verify* the signatures it creates. SSH format only.
allowed_signers_pathstringoptional
Override path for the allowed signers file. Defaults to "~/.ssh/allowed_signers".
formatstringoptional
Signing format. Defaults to "ssh".
keystring
The signing key (e.g. an SSH public key).

git.UserConfig ​

emailstring
Email address for commits.
namestring
Full name for commits.