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.

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.

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:

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:

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.