GOT.CONF(5)

🎀 GOT.CONF(5) 🎀

okay bestie, so this is the File Formats Manual page for got.conf — the Game of Trees configuration file. it's a (5) page which means it's about a file format, not a command. and honestly? it's giving "quietly runs your whole git life" energy. let's get into it 💅

---

✨ NAME ✨

got.conf — Game of Trees configuration file 🦋

---

💖 DESCRIPTION 💖

got.conf is the run-time configuration file for got(1). no cap.

so here's the vibe: got.conf can live in two places, and they do different things:

• in the root directory of a Git repository → it holds repository-wide settings 🌸
• in the .got meta-data directory of a work tree → it overrides those repository-wide settings, but only for got(1) commands you run inside that work tree 👑

the file format is line-based — one configuration directive per line. that's it. that's the whole structure. iconic.

Comments can go literally anywhere in the file, using a hash mark (#), and they run to the end of the current line. so go ahead and annotate, bestie, live your truth 🫶

now the tricky bit — quoting rules, pay attention:

• Argument names that don't begin with a letter, a digit, or an underscore must be quoted
• Reserved words (like author, remote, or port) must be quoted too
• Arguments containing whitespace should be wrapped in double quotes (")

The available configuration directives are as follows:

---

🌟 author “Real Name <email address>” 🌟

Configure the author's name and email address for got commit and got import when operating on this repository.

Author information specified here overrides the GOT_AUTHOR environment variable.

heads up: because git(1) may fail to parse commits without an email address in author data, got(1) attempts to reject author information that's missing an email address. so like, put the email in. fr fr.

---

🌟 signer_id signer-id 🌟

Configure a signer-id to sign tag objects. This key will be used to sign all tag objects unless it gets overridden by got tag -s signer-id.

For SSH-based signatures, signer-id is the path to a file which may refer to either:

• a private SSH key, or
• a public SSH key with the private half available via ssh-agent(1)

---

🌟 allowed_signers path 🌟

Configure a path to the "allowed signers" file, which contains a list of trusted SSH signer identities.

This file gets passed to ssh-keygen(1) during verification of SSH-based signatures with got tag -V. The format of the "allowed signers" file is documented in the ALLOWED SIGNERS section of ssh-keygen(1).

⚠️ real talk: verification of SSH-based signatures is impossible unless the allowed_signers option is set in got.conf. not "annoying", not "degraded" — impossible. periodt.

---

🌟 revoked_signers path 🌟

Configure a path to the optional "revoked signers" file, which contains a list of revoked SSH signer identities.

This file is passed to ssh-keygen(1) during signature verification with got tag -V. Revoked identities are no longer considered trustworthy and verification of relevant signatures will fail. 💀

---

🌟 remote name {...} 🌟

Define a remote repository. The name you pick here can be used to refer to that remote repository on the command line of got fetch and got send. cute, right?

when repositories are shared between multiple users on the system, it is recommended that users configure their trusted remote repositories in each of their work-trees' got.conf files, overriding the corresponding repository-wide settings. this can avoid potentially undesirable connections to remote repositories that other users placed into the shared repository's got.conf file. (yes, that's a real risk. vibe check your shared repos 🚨)

Information about a repository is declared in a block of options enclosed in curly brackets:

🌈 server hostname 🌈

Defines the hostname to use for contacting the remote repository's server.

🌈 repository path 🌈

Defines the path to the repository on the remote repository's server.

🌈 protocol scheme 🌈

Defines the protocol to use for communicating with the remote repository's server.

The following protocol schemes are supported:

• git — The Git protocol as implemented by the git-daemon(1) server. Use of this protocol is discouraged since it supports neither authentication nor encryption. (it's giving "postcard, no envelope" 😭)
• ssh — The Git protocol wrapped in an authenticated and encrypted ssh(1) tunnel. With this protocol the hostname may contain an embedded username for ssh(1) to use: user@hostname
• http — The "smart" Git HTTP protocol. Not compatible with servers using the "dumb" Git HTTP protocol.
  • The "smart" Git HTTP protocol is supported by got clone and got fetch, but not by got send. To send from a repository cloned over HTTP, add a send block (see below) to ensure that the "ssh://" protocol will be used by got send.
  • Use of this protocol is discouraged since it supports neither authentication nor encryption.
• https — The "smart" Git HTTP protocol wrapped in SSL/TLS. ✨

🌈 port port 🌈

Defines the port to use for connecting to the remote repository's server. The port can be specified by number or by name. The port name to number mappings are found in the file /etc/services; see services(5) for details.

If not specified, the default port of the specified protocol will be used. 🎀

🌈 branch {branch ...} 🌈

Specify one or more branches which got fetch and got send should fetch from and send to the remote repository by default.

The list of branches specified here can be overridden at the got fetch and got send command lines with the -b option.

🌈 fetch_all_branches yes | no 🌈

This option controls whether got fetch will fetch all branches from the remote repository by default.

If enabled, this behaviour can be overridden at the got fetch command line with the -b option, and any branch configuration settings for this remote repository will be ignored. 👀

🌈 reference {reference ...} 🌈

Specify one or more arbitrary references which got fetch should fetch by default, in addition to the branches and tags that will be fetched.

The list of references specified here can be overridden at the got fetch command line with the -R option.

got fetch will refuse to fetch references from the remote repository's "refs/remotes/" or "refs/got/" namespace. In any case, references in the "refs/tags/" namespace will always be fetched and mapped directly to local references in the same namespace.

🌈 mirror_references yes | no 🌈

This option controls the behaviour of got fetch when updating references.

Enabling this option can lead to the loss of local commits. Maintaining custom changes in a mirror repository is therefore discouraged. be careful, bestie, this one bites 😭

If this option is not specified or set to no, got fetch will map references of the remote repository into the local repository's "refs/remotes/" namespace.

If this option is set to yes, all branches in the "refs/heads/" namespace will be updated directly to match the corresponding branches in the remote repository.

🌈 fetch {...} 🌈

An optional fetch block may contain any of the following configuration settings for use by got fetch, overriding corresponding settings in the containing remote name {...} block.

• server hostname
• repository path
• protocol scheme
• port port
• branch {branch ...}

🌈 send {...} 🌈

An optional send block may contain any of the following configuration settings for use by got send, overriding corresponding settings in the containing remote name {...} block.

• server hostname
• repository path
• protocol scheme
• port port
• branch {branch ...}

---

🎀 FILES 🎀

• got.conf — If present, got.conf located in the root directory of a Git repository supersedes any relevant settings in Git's config file. 👑
• .got/got.conf — If present, got.conf located in the .got meta-data directory of a got(1) work tree supersedes any relevant settings in the repository's got.conf configuration file and Git's config file. double override, main character energy.

---

🌸 EXAMPLES 🌸

Configure author information:

author "Flan Hacker <flan_hacker@openbsd.org>"

Remote repository specification for the Game of Trees repository:

remote "origin" {
        server anonymous@got.gameoftrees.org
        protocol ssh
        repository got
        branch { "main" }
}

Mirror the OpenBSD src repository from Github:

remote "origin" {
        repository "openbsd/src"
        server git@github.com
        protocol git+ssh
        mirror_references yes
}

Fetch changes via the Git protocol and send changes via the SSH protocol:

remote "origin" {
        repository my_repo
        server git.example.com
        protocol git
        send {
                server git@git.example.com
                protocol ssh
        }
}

---

👀 SEE ALSO 👀

got(1), git-repository(5), got-worktree(5)

---

⚠️ CAVEATS ⚠️

got.conf offers no way to configure the editor spawned by got commit, got histedit, got import, or got tag.

This is deliberate — and it prevents potential arbitrary command execution as another user when repositories or work trees are shared between users. so no, you can't put your editor in here, and that's a feature not a bug 🫶

Users should set their VISUAL or EDITOR environment variables instead. 💅

---

okay that's the whole page!! this one came from the Debian build, version stamp $Mdocdate$, and it's GOT.CONF(5) bestie 🦋✨ go configure something, you got this 💖