git-annex-push(1)

📦
version 10.20261026 · 3 versions
, in alpine 3.24, arch rolling

💅 NAME

git-annex-push — push content to remotes 🚀 (yes bestie, that's the whole vibe: it pushes content)

okay so quick note before we dive in — this whole page lives in the git-annex manual, section 1, and it's giving "the glow-up your git push never had". let's go ✨

🌸 SYNOPSIS

git annex push [remote ...]

🦋 DESCRIPTION

okay so this command pushes content to remotes — and it's not just doing one thing. It uploads both the git repository content and the content of your annexed files. two-for-one slay 💅

You could totally just run git push and git-annex copy by hand to do the exact same thing, ngl. But this command handles a bunch of little details for you — including making sure the git-annex branch actually gets pushed to the remote. like, it's the responsible friend who remembers the stuff you'd forget 🙈

So here's a thing that surprises people: with git-annex, remotes are often not bare repositories. That's on purpose — it's genuinely helpful to add remotes for nearby machines where you want the same annexed content to live. But pushing to a non-bare remote will not normally update that remote's current branch with changes from your local repository. (Unless, that is, the remote is configured with receive.denyCurrentBranch=updateInstead — then it's a different story.) Instead, when it detects a remote like that, this command pushes to the remote's synced/master (and similar with other branches). Then when git-annex pull (or git-annex sync) is later run on the remote, it merges the synced/ branches that got pushed to it. teamwork, but make it version control 🫶

Some special remotes let you export a whole tree of files to them (exporttree=yes), and this command can push to those remotes too, as well as to regular git remotes. For the full tea on how those special remotes work, go read git-annex-export(1). But heads up — for this command to export to a special remote, remote.<name>.annex-tracking-branch also has to be configured, and it must have the same value as the branch you currently have checked out. no matching branch, no export, periodt 💀

If git-annex-adjust(1) has been used to check out an adjusted branch, this command propagates changes that were made back to the parent branch — without propagating the adjustments themselves. iconic behavior honestly 👑

Normally, this tries to upload the content of each annexed file that's in the working tree, to any remote it's pushing to that doesn't already have a copy. Want to control which files get uploaded to a given remote? Configure that remote's preferred content. And plot twist: when a file is not the preferred content of a remote, this command will try to drop that file's content from it 😭 So yeah, preferred content settings are kind of a big deal — see git-annex-preferred-content(1).

✨ OPTIONS ✨

  • [remote] — so by default this command pushes to all available remotes… minus the ones that have remote.<name>.annex-push (or remote.<name>.annex-sync) set to false, and minus the ones with remote.<name>.annex-readonly set to true (read-only remotes said "not today" 🙅‍♀️). But if you specify remote names (or remote groups), you get to pick exactly which ones to push to. choose your fighters, bestie 💖
  • --fast — only push to the remotes with the lowest annex-cost value configured. 🏃‍♀️ When you give a list of remotes (or remote groups), it picks from among those; otherwise it picks from among all remotes. fastest one wins, no cap ⚡
  • --only-annex, -a, --not-only-annex — only push the git-annex branch and annexed content to remotes, and not other git branches. 🎀 The annex.synconlyannex configuration can be set to true to make this the default behavior — and if you ever need to override a setting like that, just use --not-only-annex. Also: when this is combined with --no-content, only the git-annex branch gets pushed. that's it. that's the whole push 🫡
  • --no-content, -g, --content — use --no-content or -g to avoid uploading (and dropping) the content of annexed files. 🙈 If you find yourself using --no-content a lot, you can set the annex.synccontent configuration to false so content doesn't get uploaded by default — and the --content option overrides that configuration. 💜
  • --content-of=path, -C path — only upload (or drop) annexed files in the given path. 🍓 This option can be repeated multiple times with different paths. But note: this option does not prevent exporting other files to an "exporttree=yes" remote. (sneaky little caveat, keep it in mind 👀)
  • --all, -A — usually this command operates on annexed files in the current branch. This option makes it operate on all available versions of all annexed files (when preferred content settings allow). ⭐ Also note: preferred content settings that use include= or exclude= will only match the version of files currently in the work tree — but not past versions of files. yeah. that one's important, don't skip it 😭
  • --jobs=N, -JN — enables parallel pushing with up to the specified number of jobs running at once. For example: -J10 🔥 Setting this to "cpus" will run one job per CPU core. go off, multicore queen 👑
  • --cleanup — removes the local and remote synced/ branches, which were created and pushed by git-annex push or git-annex sync. 🧹 This option prevents all other activities. like, it's the only thing it'll do. one-track mind 💅

Also — the git-annex-common-options(1) can be used. don't forget the shared options, bestie, they're free real estate 💖

🌈 SEE ALSO

👑 AUTHOR

Joey Hess <id@joeyh.name> — the main character who wrote all of this 🫶

ok that's the whole page!! source is the git-annex manual, and the footer line just says git-annex-push(1) (the man page title itself). no invented dates here, bestie — just the facts, wrapped in glitter. stay synced 💖✨🎀🦋
📦 where this page comes from