git-annex-sim(1)

git-annex-sim 💖✨

okay bestie, welcome to the General Commands Manual page for git-annex-sim, and no cap, this one is a whole vibe. it's a simulator. it's a time machine for your repos. it's giving science lab but make it git. 🧪🦋

---

✨ NAME ✨

git-annex-sim — simulate a network of repositories 💅

---

✨ SYNOPSIS ✨

git annex sim start [my.sim]

git annex sim command

git annex sim show

git annex sim end

git annex sim run my.sim

---

✨ DESCRIPTION ✨

so basically, this command simulates how git-annex behaves across a whole network of repositories, and it figures out which files would end up in which repositories based on your config: preferred content, numcopies, trust level, all of it. it's literally running the whole thing in a fake little world so you don't have to actually do it for real. 🔮

the input to the simulation is a sim file, and/or sim commands that you run after starting it. those take the form git annex sim command, with the command in the exact same format used in the sim file (peep the sim commands list below). for example, git annex sim step 1 runs the simulation one step. easy. ✨

the simulation keeps a log as it runs, and that log contains the entire simulation input, plus the actions performed in the simulation, plus the results of the simulation. use git-annex sim show to display the log. this means you can re-run the same simulation later AND analyze the results of the simulation. it's giving receipts, and honestly? we love receipts. 📝

use git annex sim end to finish the simulation, and clean up. 🧹

as a convenience, to run a sim from a file and then stop it, use git-annex sim run. if there's a problem running the sim, it will be shown before it is stopped. thoughtful. 💖

⚠️ okay important warning bestie: interrupting this command while it's running may leave the simulation in an inconsistent state. and running multiple sim commands at the same time can do that too. BUT — it is safe to run git annex sim visit while running other sim commands. so like, that one's fine. 😌

---

🎀 THE SIM FILE 🎀

this text file configures the simulation AND reports on the results of the simulation. every line takes the form of a command followed by parameters to the command. lines starting with # or -- are comments. 💬

here's an example sim file, look at her go:

 # add repositories to the simulation and connect them as remotes
 init foo
 init bar
 connect foo <-> bar

 # add a special remote
 initremote baz
 connect foo -> baz <- bar

 # configure repositories
 numcopies 2
 group foo client
 wanted foo standard
 group bar archive
 wanted bar standard
 wanted baz include=*.mp3

 # add annexed files in the working tree to the simulation, as if they
 # were just added to repository foo
 addtree foo include=*.mp3
 addtree foo include=*.jpg
 addtree foo include=bigfiles/

 # add simulated annexed files
 add bigfile 100gb bar
 add hugefile 10tb foo

 # run the simulation forward by ten steps
 step 10

 # remove foo's remote bar and see if a new file added to foo reaches bar
 disconnect foo -> bar
 add foo.mp3 2mb foo
 step 5

---

💅 SIM COMMANDS 💅

this is the full set of commands that can be used in the sim file as well as passed to git annex sim while a simulation is running. every single one, no skips, no cuts. 🫶

• init name — initialize a simulated repository, and give it a name that will be used in the simulation.
• initremote name — initialize a simulated special remote.
• use name here|remote|description|uuid — use an existing repository in the simulation, keeping its existing configuration (trust level, groups, preferred and required content, maxsize, and the groupwanted configuration of its groups).

the repository gets a name for the purposes of the simulation. the repository to use can be specified by remote name, uuid, etc. example: use myrepo here

• visit repo [command] — runs the specified shell command inside the simulated repository, and waits for it to exit.

when no shell command is specified, it runs an interactive shell. 🐚

the command is run in a git repository whose git-annex branch contains the state of that simulated repository. this lets you run any git-annex commands, like git-annex whereis, to examine the state of the simulation. you should avoid making any changes to git-annex state. look but don't touch, bestie. 🙈

• connect repo [<-|->|<->] repo [...] — add a connection between two or more repositories. the arrow indicates which direction the connection runs, and it can be bidirectional. for example, connect foo -> bar makes bar be a remote of foo, while connect foo <-> bar makes each be the remote of the other. a chain of connections can extend to many repositories, eg connect foo -> bar -> baz -> foo 🔗
• disconnect repo [<-|->|<->] repo [...] — removes connections between repositories.

for example, disconnect foo -> bar makes foo no longer have bar as a remote. ✂️

• addtree repo expression — adds annexed files from the git repository to the simulation, making them be present in the specified repository.

the expression is a preferred content expression (see git-annex-preferred-content(1)) specifying which annexed files to add. while it is possible to include all or a large number of files this way, note that often it's more efficient to simulate a small quantity of files that have the particular properties you are interested in. quality over quantity, periodt. ✨

when run in a subdirectory of the repository, only files in that subdirectory are considered for addition.

this can be used with the same files more than once, to make multiple repositories in the simulation contain the same files. 🔁

• add filename size repo [repo ...] — create a simulated annexed file with the specified filename and size, that is present in the specified repository, or repositories.

the size can be specified using any usual units, eg 10mb or 3.3terabytes. 📏

the filename cannot contain a space.

this stages a file in the index, so that regular git-annex commands can be used to query the state of the simulated annexed file. if there is already an annexed file by that name, it will be overwritten with the new file.

note that the simulation does not cover adding conflicting files to different repositories. the files in the simulation are the same across all simulated repositories. 🫠

• addmulti N suffix minsize maxsize repo [repo ...] — add multiple simulated annexed files, with random sizes in the range between minsize and maxsize.

the files are named by combining the number, which starts at 1 and goes up to N, with the suffix.

for example:

 addmulti 100 testfile.jpg 100kb 10mb foo

that adds files named 1testfile.jpg, 2testfile.jpg, etc. 🎉

note that adding a large number of files to the simulation can slow it down and make it use a lot of memory. heavy, bestie, be careful. 💀

• step N — run the simulation forward by this many steps.

on each step of the simulation, one file is either transferred or dropped, according to the preferred content and other configuration.

if there are no more files that can be either transferred or dropped according to the current configuration, a message will be displayed to indicate that the simulation has stabilized. 😌

this also simulates git pull and git push being run in each repository, as needed in order to find additional things to do.

• stepstable N — run the simulation forward by this many steps, at which point it is expected to have stabilized.

if the simulation does not stabilize, the command will exit with a nonzero exit state. 🚨

• action repo getwanted remote — simulate the repository getting files it wants from the remote. 🫳
• action repo dropunwanted — simulate the repository dropping files it does not want, when it is able to verify enough copies exist on remotes.
• action repo dropunwantedfrom remote — simulate the repository dropping files from the remote that the remote does not want, when it is able to verify enouh copies exist.
• action repo sendwanted remote — simulate the repository sending files that the remote wants to it. 📤
• action repo gitpush remote — simulate the repository pushing the git-annex branch to the remote.
• action repo gitpull remote — simulate the repository pulling the git-annex branch from the remote.
• action repo pull remote — simulate the equivilant of git-annex-pull(1), by combining the actions gitpull, getwanted, and dropunwanted.
• action repo push remote — simulate the equivilant of git-annex-push(1) by combining the actions sendwanted, dropunwantedfrom, and gitpush.
• action repo sync remote — simulate the equivilant of git-annex-sync(1) by combining the actions gitpull, getwanted, sendwanted, dropunwanted, and gitpush. the whole combo meal. 🍟
• action [...] while action [...] — simulate running the two actions concurrently. while the simulation only actually simulates one thing happening at a time, when the actions each operate on multiple files, they will be interleaved randomly. 🎲

any number of actions can be combined this way.

for example:

 action foo dropunwanted while action bar getwanted foo

in this example, bar may or may not get a file before foo drops it.

• seed N — sets the random seed to a given number. using this should make the results of the simulation deterministic. the output sim file always has the random seed included in it, so it can be used to replay the simulation. 🌱✨
• present repo file — this indicates the expected state of the simulation at this point. the repository should contain the content of the file. if it does not, the discrepancy will be indicated on standard error, and the git-annex sim command will eventually exit nonzero.

this is added to the output sim file as the simulation runs.

• notpresent repo file — this indicates the expected state of the simulation at this point. the repository should not contain the content of the file. if it does, the discrepancy will be indicated on standard error, and the git-annex sim command will eventually exit nonzero.

this is added to the output sim file as the simulation runs.

• numcopies N — sets the desired number of copies. this is equivilant to git-annex-numcopies(1).

note that other configuration that sets numcopies, such as .gitattributes files, is not used by the simulation. 👀

• mincopies N — sets the minimum number of copies. this is equivilant to git-annex-mincopies(1).
• trustlevel repo trusted|untrusted|semitrusted|dead — sets the trust level of that repo. It's literally the same thing as git-annex-trust(1), git-annex-untrust(1), etc. Just, like, the sim version 💅
• wanted repo expression — sets up the preferred content of a repo. Same as git-annex-wanted(1), no cap.
• required repo expression — sets up the required content of a repo. Same as git-annex-required(1).
• groupwanted group expression — sets up the groupwanted expression. Same as git-annex-groupwanted(1).
• randomwanted repo term... — sets the preferred content of a repo to a random expression, built by smashing together a random selection of the terms you give it with "and", "or", and "not". Chaos generator fr fr 🎲

So for example, "randomwanted foo exclude=*.x include=*.x largerthan=100kb" might spit out an expression like "exclude=*.x or not largerthan=100kb and include=*.x", or it might give you "include=*.x and exclude=*.x". You don't get to pick, bestie, that's the whole vibe.

• randomrequired repo term... — same deal, but it sets the required content of a repo to a random expression.
• randomgroupwanted group term... — and again, but this time it sets the groupwanted to a random expression.
• group repo group — adds a repo to a group. Same as git-annex-group(1).
• ungroup repo group — removes a repo from a group. Same as git-annex-ungroup(1).
• metadata filename expression — changes the metadata of the simulated file. The expression uses the exact same format as the --set option of the git-annex-metadata command. Like: metadata foo year=2025 ✨
• maxsize repo size — sets the maximum size of a repo. Same as git-annex-maxsize(1).
• rebalance [on|off] — "rebalance on" is the equivalent of passing the --rebalance option to git-annex, and "rebalance off" undoes that. Turning it back off, we love a reversible queen 👑

For example:

maxsize foo 1tb
rebalance on
step 100
rebalance off

• clusternode name repo — simulates a repo being a node of a cluster, which you can then refer to using the name you picked. 🫶

Instead of simulating a cluster gateway as its own separate entity, any connection to a cluster node with that name gets treated as accessing that repo via the same cluster gateway.

And because a cluster gateway knows about every change made to nodes through it, any repo that has a connection to a cluster node will immediately know about changes made via that node — no simulated git pull needed. Instant gossip, iconic.

Wanna simulate a repo being a node of more than one cluster, or sitting behind multiple gateways in the same cluster? Just run this command again to give it multiple names. Slay.

---

✨ OPTIONS ✨

The git-annex-common-options(1) can be used. That's it, that's the options section, go wild 🦋

---

🌸 EXAMPLES 🌸

git-annex ships with a whole lil collection of sim files, right here: <https://git-annex.branchable.com/sims/> 🎀

---

👀 SEE ALSO 👀

• git-annex(1)
• git-annex-test(1)

---

💖 AUTHOR 💖

Joey Hess <id@joeyh.name> — the main character, honestly 👑

---

and that's the whole page bestie!! this was git-annex-sim(1), part of the git-annex family, written by Joey Hess and served up with the date and version the manpage came with. go forth and simulate responsibly, ily 🫶💜