git-annex/ git-annex-adjust

# NAME

git-annex adjust - enter an adjusted branch

# SYNOPSIS

git annex adjust `--unlock|--lock|--fix|--hide-missing [--unlock|--lock|--fix]|--unlock-present`

# DESCRIPTION

Enters an adjusted form of the current branch. The annexed files will be treated differently. For example with --unlock all annexed files will be unlocked.

The adjusted branch will have a name like "adjusted/master(unlocked)". Since it's a regular git branch, you can use `git checkout` to switch back to the original branch at any time.

This allows changing how annexed files are handled, without making changes to a public branch with commands like `git-annex unlock`.

While in the adjusted branch, you can use git-annex and git commands as usual. Any commits that you make will initially only be made to the adjusted branch.

To propagate commits from the adjusted branch back to the original branch, and to other repositories, as well as to merge in changes from other repositories, run `git annex sync`. This will propagate changes that you've made such as adding/deleting files, but will not propagate the adjustments made by this command.

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 such merges cannot be propagated from the adjusted branch back to the original branch. To avoid those problems, use `git annex merge otherbranch`.

Re-running this command with the same options while inside the adjusted branch will update the adjusted branch as necessary (eg for `--hide-missing` and `--unlock-present`), and will also propagate commits back to the original branch.

# OPTIONS

- `--unlock`

  Unlock all annexed files in the adjusted branch. This allows annexed files to be modified.

  Normally, unlocking a file requires a copy to be made of its content, so that its original content is preserved, while the copy can be modified. To use less space, annex.thin can be set to true before running this command; this makes a hard link to the content be made 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.

  When 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. This is because it's not possible for those git commands to add files locked.

- `--fix`

  Fix the symlinks to annexed files to point to the local git annex object directory. This can be 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 is not immediately changed when content availability changes, so if you `git annex drop` files, they will become broken links in the usual way. And when files that were missing are copied into the repository from elsewhere, they won't immediatly become visible in the branch.

  To update the adjusted branch to reflect changes to content availability, run `git annex adjust --hide-missing` again. Or, to automate 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 download missing files from remotes. It also updates the adjusted branch after transferring content.

  This 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 provides the benefits of working with unlocked files, but makes it easier to see when the content of a file is not missing, since it will be a broken symlink.

  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.

  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.

- Also the git-annex-common-options(1) can be used.

# SEE ALSO

git-annex(1)

git-annex-unlock(1)

git-annex-lock(1)

git-annex-upgrade(1)

git-annex-sync(1)

git-annex-view(1)

# AUTHOR

Joey Hess id@joeyh.name

Warning: Automatically converted into a man page by mdwn2man. Edit with care.

comment 7
Thanks for the help on where to put the question, joey. I have deleted and moved my previous post.
Comment by lell — Wed Oct 29 14:05:27 2025
comment 6

@lell this is a man page, it's really not a place to file bug reports or discuss in detail complicated scenarios.

Please use bugs and forum for such things.

Comments are open on this page in case someone has a suggestion to improve this documentation, not for general discussion about the feature.

Comment by joey — Wed Oct 29 14:05:27 2025
Get missing files in --hide-missing branch
When in an hide-missing adjusted branch, is there any way to "git annex get" a missing file without switching branches first. Respectively, is there any way to find/list missing files without switching branches?
Comment by mario — Wed Oct 29 14:05:27 2025
Thank you
This is is a great feature, especially `--hide-missing`! I really missed this in the past. (Strangely it took me until now to notice that you implemented it.) Thank you.
Comment by mario — Wed Oct 29 14:05:27 2025
comment 2

`git annex fix` fixes up the symlinks before they're committed. It's run by the pre-commit hook, so even when annexed files are manually moved around, the symlinks that get committed are always right.

So then, if the symlinks committed are always right, how would `git annex adjust --fix` be useful? Well, there are ways to check out git repositories that make the .git directory not be in the usual place. For example, when using submodules, git puts that directory in a different place. And then the committed symlinks won't point to .git. So, `git annex adjust --fix` is useful as a way to adjust the symlinks locally, without committing any changes to them, in that kind of situation.

Comment by joey — Wed Oct 29 14:05:27 2025
difference with git-annex-fix?

From git-annex-fix manual:

       Fixes up symlinks that have become broken to again point to annexed content.
       This is useful to run manually when you have been moving the symlinks around, but is done automatically when committing a change with git too.
       Also, adjusts unlocked files to be copies or hard links as configured by annex.thin.

So what is the difference between that and git-annex adjust --fix?

Comment by ynikitenko — Wed Oct 29 14:05:27 2025
Comments on this page are closed.