git-annex-adjust(1)

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

💅 git-annex-adjust — bestie's guide to entering an adjusted branch ✨

okay so real quick, this is page git-annex-adjust(1) from the General Commands Manual — yes it's a real grown-up manpage and yes i'm about to make it sparkle. let's go 🫶

🌸 SYNOPSIS 🌸

git annex adjust
--unlock|--lock|--fix|--hide-missing|--unlock-present|--hide-unwanted

🦋 DESCRIPTION 🦋

So basically this command enters an adjusted form of the current branch, and in that adjusted form your annexed files get treated differently. Like, with --unlock every annexed file becomes unlocked. iconic behavior honestly.

The adjusted branch gets a name like "adjusted/master(unlocked)" — it's giving main character energy but with a whole descriptive name. And the way that it's a regular git branch?? you can just use git checkout to bounce back to the original branch whenever you want. no cap. 💖

The whole point: you can change how annexed files are handled without messing with a public branch using commands like git-annex unlock. big win for not embarrassing yourself in front of your collaborators.

While you're chilling in the adjusted branch you can use git-annex and git commands as usual, fr fr. Any commits you make will initially only land on the adjusted branch. (yes, initially. keep reading bestie 😌)

To propagate commits from the adjusted branch back to the original branch and out to other repositories — and also to merge in changes from other repositories — you run git annex sync. It'll propagate the changes you've made like adding/deleting files, but it will not propagate the adjustments this command made. that's the whole point of them, they're a local vibe ✨

⚠️ When in an adjusted branch, using git merge otherbranch is often not ideal, because merging a non-adjusted branch may lead to unnecessary merge conflicts, or add files in non-adjusted form. And those merges can't be propagated from the adjusted branch back to the original branch. To dodge all that, use git annex merge otherbranch instead. lowkey important, don't skip this one 💀

Re-running this command with the same options while you're inside the adjusted branch will update the adjusted branch as necessary (eg for --hide-missing, --unlock-present, and --hide-unwanted), and it will also propagate commits back to the original branch. so it's a little refresh + a little sync, obsessed 💅

✨ OPTIONS ✨

  • --unlock — Unlock all annexed files in the adjusted branch. This lets annexed files be modified. 🔓

Normally, unlocking a file requires a copy to be made of its content, so the original content is preserved while the copy gets modified. To use less space, annex.thin can be set to true before running this command — that makes a hard link to the content instead of a copy (when supported by the file system). While this can save considerable disk space, any modification made to a file will cause the old version of the file to be lost from the local repository. So enable annex.thin with care bestie, i'm serious 😭

When you're in an adjusted unlocked branch, git annex add will add files unlocked instead of the default behavior of adding them locked.

  • --lock — Lock all annexed files in the adjusted branch. This may be preferred by those who like seeing broken symlinks when the content of an annexed file is not present. 🔒

When in an adjusted locked branch, git annex add will add files locked, as usual. However, git add (and git commit -a etc) still add files unlocked — because it's not possible for those git commands to add files locked. not their fault, they just don't have the range 🙈

  • --fix — Fix the symlinks to annexed files so they point to the local git annex object directory. Super useful if a repository is checked out in an unusual way that prevents the symlinks committed to git from pointing at the annex objects. 🩹
  • --hide-missing — Only include annexed files in the adjusted branch when their content is present.

The adjusted branch does not immediately change when content availability changes, so if you git annex drop files, they'll become broken links in the usual way. And when files that were missing get copied into the repository from elsewhere, they won't immediately become visible in the branch. (the branch is not a mind reader, give it a sec)

To update the adjusted branch to reflect changes to content availability, run git annex adjust --hide-missing again. Or, to automate the updates, set the annex.adjustedbranchrefresh config. ⚙️

Despite missing files being hidden, git annex sync --content will still operate on them, and can be used to retrieve missing files from remotes. It also updates the adjusted branch after transferring content. slay.

To retrieve specific missing files, use eg:

git-annex get --branch=master --include=foo

The --hide-missing option can be combined with --unlock, --lock, or --fix. 💜

  • --unlock-present — Unlock files whose content is present, and lock files whose content is missing. This gives you the benefits of working with unlocked files, but makes it easier to see when the content of a file is not missing, since it'll be a broken symlink. honestly a vibe check for your files 👑

The adjusted branch is not immediately changed when content availability changes, so when you git annex get files, they will remain locked. And when you git annex drop files, they will remain locked and so will not be broken symlinks. yeah. the branch is on its own timeline 🕰️

To update the adjusted branch to reflect changes to content availability, run git annex adjust --unlock-present again. Or, to automate updates, set the annex.adjustedbranchrefresh config. Or use git-annex sync --content, which updates the branch after transferring content.

  • --hide-unwanted — Only include annexed files in the adjusted branch when they are preferred content of the repository, as configured by git-annex wanted. 🎀

Note that when the preferred content expression uses present, files are only wanted when their content is present. The adjusted branch is not immediately changed when content availability changes. To update the adjusted branch to reflect changes to content availability, run git-annex adjust --hide-unwanted again. Or, to automate updates, set the annex.adjustedbranchrefresh config.

The --hide-unwanted option can be combined with --unlock, --lock, or --fix. 🌈

  • --force — Allow overwriting an existing adjusted branch with a new version. 💥

For example, suppose you started with branch foo checked out and used git-annex adjust --unlock. But then foo was rebased, and you checked out that new version of foo. Running git-annex adjust --unlock again would fail because of the existing adjusted branch. Using --force would overwrite that adjusted branch. problem solved, no cap.

Also the git-annex-common-options(1) can be used. (free extras, we love her 💅)

🧚 SEE ALSO 🧚

👑 AUTHOR 👑

Joey Hess <id@joeyh.name> — the icon who wrote this. thank you for your service 🫡

and that's the whole page bestie!! this was git-annex-adjust(1) from the General Commands Manual, transcribed with love by your locally-installed git-annex docs 💖 now go forth and adjust that branch ✨🎀🦋

📦 where this page comes from