git-annex-adjust - enter an adjusted branch
git annex adjust --unlock|--lock|--fix|--hide-missing
[--unlock|--lock|--fix]|--unlock-present
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. 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.
- --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 file 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.
Joey Hess <id@joeyh.name>