GOTADMIN(1)

GOTADMIN 💅

okay bestie, so this is the gotadmin manual page — it's section 1 (General Commands Manual) of the gotadmin docs, and it's literally the repository administration tool for the got(1) version control system. sit down, get a snack, we're doing this together 🫶

---

✨ SYNOPSIS ✨

gotadmin [-hV] command [arg ...]

that's it. that's the whole shape of it. a command, some args, and a couple of global flags. slay.

---

🌸 DESCRIPTION 🌸

so gotadmin is the repository maintenance tool for the got(1) version control system. it's giving backstage crew energy — you don't see it on stage but nothing works without it.

got(1) stores the history of tracked files in a Git repository, exactly like the Git version control system uses. and gotadmin is the girl who hands you the commands for inspecting and manipulating the on-disk state of those Git repositories. the repository format itself is described over in git-repository(5), if you want the deep lore.

gotadmin has both global options and command-specific options. and listen — global options have to come before the command name. no cap. order matters, bestie.

💫 Global Options

• -h — display usage information and exit immediately. like, "here's how you use me, bye" 👋
• -V, --version — display program version and exit immediately.

---

👑 THE COMMANDS 👑

here's the whole roster. every single one, in order, no skips:

🌱 init [-A hashing-algorithm] [-b branch] repository-path

create a brand new empty repository at the specified repository-path. fresh out the box, baby ✨

after gotadmin init, the new repository must be populated before got checkout can be used. so you can't just waltz in and check out nothing. options for populating:

• the got import command can be used to populate the new repository with data from a local directory.
• alternatively, on a server running gotd(8), the new repository can be made available to got(1) or git(1) clients by adding the repository to gotd.conf(5) and restarting gotd(8). clients may then clone the new repository from the server, populate the cloned repository, and then populate the new repository on the server via got send or git push.

💖 options for gotadmin init

• -A hashing-algorithm — configure the repository's hashing-algorithm used for the computation of Git object IDs. possible values are sha1 (the default) or sha256. pick your fighter.
• -b branch — make the repository's HEAD reference point to the specified branch instead of the default branch "main". main character behavior but make it custom 💅

fyi, the gotadmin init command is equivalent to got init. same thing, different entrance.

🔍 info [-r repository-path]

display information about a repository. what's in the info dump, you ask?

• some configuration settings from got.conf(5)
• the object ID hashing algorithm
• the number of objects stored in the repository, in packed or loose form
• the current on-disk size of these objects

the receipts, basically. 🧾

💖 options for gotadmin info

• -r repository-path — use the repository at the specified path. if not specified, assume the repository is located at or above the current working directory. and if this directory is a got(1) work tree, use the repository path associated with this work tree.

📦 pack [-aDq] [-r repository-path] [-x reference] [reference ...]

generate a new pack file and a corresponding pack file index. by default, add any loose objects which are reachable via any references to the generated pack file. packing it up, cute.

if one or more reference arguments is specified, only add objects which are reachable via the specified references. each reference argument may either specify a specific reference or a reference namespace, in which case all references within this namespace will be used.

⚠️ gotadmin pack always ignores references in the refs/got/ namespace, effectively treating such references as if they did not refer to any objects. not me ghosting the entire namespace 💀

💖 options for gotadmin pack

• -a — add objects to the generated pack file even if they are already packed in a different pack file. unless this option is specified, only loose objects will be added.
• -D — force the use of ref-delta representation for deltified objects. if this option is not specified, offset-deltas will be used to represent deltified objects.
• -q — suppress progress reporting output. shhh 🤫
• -r repository-path — use the repository at the specified path. if not specified, assume the repository is located at or above the current working directory. if this directory is a got(1) work tree, use the repository path associated with this work tree.
• -x reference — exclude objects reachable via the specified reference from the pack file. the reference argument may either specify a specific reference or a reference namespace, in which case all references within this namespace will be excluded. the -x option may be specified multiple times to build a list of references to exclude.

🚨 exclusion takes precedence over inclusion. if a reference appears in both the included and excluded lists, it will be excluded. the block list wins, always. periodt.

🧾 indexpack packfile-path (alias: ix)

create a pack index for the pack file at packfile-path.

a pack index is required for using the corresponding pack file with got(1). usually, a pack index will be created by commands such as gotadmin pack or got fetch as part of regular operation. the gotadmin indexpack command may be used to recover from a corrupt or missing index. and here's the iconic part: a given pack file will always yield the same bit-identical index. deterministic queen 👑

the provided packfile-path must be located within the objects/pack/ directory of the repository and should end in .pack. the filename of the corresponding pack index is equivalent, except that it ends in .idx. so .pack in, .idx out. it's giving twins.

📋 listpack [-hs] packfile-path (alias: ls)

list the contents of the pack file at packfile-path. show me what's inside 🔮

each object contained in the pack file will be displayed on a single line. the information shown includes:

• the object ID
• object type
• object offset
• object size

if a packed object is deltified against another object, the delta base will be shown as well. and the vibes differ by type:

• for offset deltas, the delta base is identified via an offset into the pack file.
• for reference deltas, the delta base is identified via an object ID.

the provided packfile-path must be located within the objects/pack/ directory of the repository and should end in .pack. the corresponding pack index must exist and can be created with gotadmin indexpack if it is missing.

💖 options for gotadmin listpack

• -h — show object sizes in human-readable form. because raw bytes are not the vibe.
• -s — display statistics about the pack file after listing objects. this includes the total number of objects stored in the pack file and a break-down of the number of objects per object type. stats girlies rise 🌈

🧹 cleanup [-anpq] [-r repository-path] (alias: cl)

repack the repository and then purge unreferenced loose objects and redundant pack files. display the amount of disk space which has been freed as a result. spring cleaning but for your git objects 🧼✨

Unreferenced objects are present in the repository but cannot be reached via any reference in the entire refs/ namespace. objects will usually become unreferenced as a result of deleting branches, tags, or other references with got branch -d, got ref -d, or got fetch -X.

Loose objects are stored as individual files in subdirectories of the repository's objects/ directory.

Packed objects are stored in pack files under objects/pack/.

if redundant copies of packed objects exist in loose form, such redundant copies will be purged. if all the objects of a pack file are present in a bigger pack file, the redundant smaller pack file will be purged. bye redundancy 💅

⚠️ references in the refs/got namespace may prevent objects from being purged. this includes: - references in the refs/got/worktree namespace created by got checkout and got update - references in the refs/got/backup namespace created by got rebase and got histedit gotadmin cleanup will only purge corresponding objects once such references have been deleted with got rebase -X, got histedit -X, or got ref -d. so like, hold up until you actually delete them.

the "preciousObjects" Git extension is intended to prevent the removal of objects from a repository. gotadmin cleanup will refuse to operate on repositories where this extension is active. it said no thank you 🙅♀️

for compatibility with Git, if a file with the extension .keep exists and corresponds to a pack file with the extension .pack then this pack file will not be removed. protected.

some Git repositories contain pack index files which lack a corresponding pack file, which is an inconsistent repository state. in such cases, gotadmin cleanup -p -n will display a list of affected pack index files. whenever possible, the missing pack files should be restored. if restoring missing pack files is not possible, then affected pack index files can be removed with gotadmin cleanup -p.

💖 options for gotadmin cleanup

• -a — delete all redundant loose and packed objects. by default, objects which are newer than an implementation-defined modification timestamp are kept on disk to prevent race conditions with other commands that add new objects to the repository while gotadmin cleanup is running. (so yes, the default is the cautious one, and -a is the no-holds-barred one.)
• -n — display the usual progress output and summary information but do not actually remove any files from disk. a dry run, a rehearsal, a dress rehearsal if you will 🎀
• -p — instead of purging unreferenced loose objects and redundant pack files, remove any pack index files which do not have a corresponding pack file.
• -q — suppress progress reporting and disk space summary output.

---

okay bestie that's the first half — hold on, there's more coming 💜

• -r repository-path — use the repository at the specified path. Didn't pass one? Then it assumes the repository is located at or above the current working directory. And if this directory is a got(1) work tree, it'll use the repository path associated with that work tree instead. convenient bestie behavior 💅

---

🌸 dump 🌸

dump [-q] [-r repository-path] [-x reference] [reference ...]

okay so dump takes the contents of the repository and yeets them out to standard output in Git bundle format. it's giving care package 🎀

If one or more reference arguments are specified, only objects which are reachable via the specified references get added. And each reference argument may either specify a specific reference or a reference namespace — in which case, bestie, all references within that namespace will be used. the whole group chat comes along 💖

The options for gotadmin dump are as follows:

• -q — suppress progress reporting output. shhh 🤫
• -r repository-path — use the repository at the specified path. If not specified, assume the repository is located at or above the current working directory. If this directory is a got(1) work tree, use the repository path associated with this work tree.
• -x reference — exclude objects reachable via the specified reference from the bundle. The reference argument may either specify a specific reference or a reference namespace, in which case all references within this namespace will be excluded. The -x option may be specified multiple times to build a list of references to exclude. stack 'em up 🫶

⚠️ Exclusion takes precedence over inclusion. If a reference appears in both the included and excluded lists, it will be excluded. the exclusion list wins, no arguments, periodt 💀

---

🦋 load 🦋

load [-nq] [-l bundle-path] [-r repository-path] [reference ...]

Read a Git bundle stream from standard input and load its data into a repository. this is the receiving end of the bundle handoff, iconic 🫶

If one or more reference arguments are provided then only load the specified references from the bundle. Otherwise, all references will be loaded. all of them. the entire friend group 😭

The options for gotadmin load are as follows:

• -l bundle-path — list references available for loading from the bundle at the specified bundle-path and exit immediately. If the -l option is specified then no reference arguments are allowed. The -l option is incompatible with the -n option. pick a lane bestie ✋
• -n — attempt to load the bundle but don't install new packfile or update any reference. Can be used to verify the integrity of the bundle. it's giving dress rehearsal 🧚
• -q — suppress progress reporting output. silence, but make it cute 🤫
• -r repository-path — use the repository at the specified path. If not specified, assume the repository is located at or above the current working directory. If this directory is a got(1) work tree, use the repository path associated with this work tree.

---

✨ EXIT STATUS ✨

The gotadmin utility exits 0 on success, and >0 if an error occurs. clean exit = slay, anything above zero = we're in our flop era 😭

---

👀 SEE ALSO 👀

got(1), tog(1), git-repository(5), got.conf(5)

go read those too, they're all part of the lore 💜

---

🌈 AUTHORS 🌈

the absolute icons who built this:

• Christian Weisgerber <naddy@openbsd.org>
• Josh Rickmar <jrick@zettaport.com>
• Klemens Nanni <kn@openbsd.org>
• Omar Polo <op@openbsd.org>
• Ori Bernstein <ori@openbsd.org>
• Stefan Sperling <stsp@openbsd.org>
• Tracey Emery <tracey@traceyemery.net>

we stan every single one of them 👑

---

💀 CAVEATS 💀

gotadmin is a work-in-progress and some features remain to be implemented. it's still cooking 🍓

At present, the user has to fall back on git(1) to perform some tasks. In particular:

• Exporting data from repositories requires git-fast-export(1).
• Importing data into repositories requires git-fast-import(1).

so yeah, sometimes you gotta call your ex (git) for a favor. it is what it is 🙈

---

🐛 BUGS 🐛

Disk space savings reported by gotadmin cleanup will be misleading if the repository contains object files that were hard-linked from another repository. Such hard-links will be created by certain git(1) commands. By itself, got(1) will never create hard-linked object files.

⚠️ read that again: the numbers can lie to you if git made hard-links behind your back. not got's fault, got stays unproblematic 💅

---

and that's the whole page bestie!! this came from the Debian build of the man page, version-tagged with that $Mdocdate$ placeholder (mysterious, we love a noncommittal date 💖), filed under GOTADMIN(1). go forth and bundle responsibly 🎀✨