mirrors/git-annex
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions

update docs

Browse source
This commit is contained in:
Joey Hess 2018-10-26 12:19:44 -04:00
parent 9f87133bf5
commit 9488a53023
No known key found for this signature in database
GPG key ID: DB12DB0FF05F8F38
1 changed files with 20 additions and 24 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

44
doc/tips/unlocked_files.mdwn
View file

@ -108,26 +108,31 @@ useful when using filesystems like FAT, and OS's like Windows that don't
support symlinks. Indeed, `git-annex init` detects such filesystems and
automatically sets up a repository to use all unlocked files.
## index gotchas
## imperfections
When git-annex gets or drops the content of an unlocked file, it updates
the file in git's worktree accordingly. That makes `git status` show
the file as modified, even though there are no changes to commit.
So git-annex then updates the index file to reflect the change to the
worktree, and prevent the file from appearing to be modified.
Unlocked files in v7 repositories mostly work very well, but there are a
few imperfections which you should be aware of when using them.
This means that when git-annex is running a command that gets or drops the
content of an unlocked file, the index will sometimes be locked. This might
prevent you from `git commit` at the same time. Or, if you have a git
commit in progress, or are running multiple git-annex processes, git-annex
may complain that the index is locked.
1. `git stash`, `git cherry-pick` and `git reset --hard` don't update
the working tree with the content of unlocked files. The files
will contain pointers, the same as if the content was not in the
repository. So after running these commands, you will need to manually
run `git annex smudge --update`.
Also, interrupting git-annex (eg with ctrl-c) before it can update the
index will leave `git status` showing modifications.
2. When git-annex is running a command that gets or drops the content
of an unlocked file, git's index will briefly be locked, which might
prevent you from running a `git commit` at the same time.
To manually update the index when git-annex was not able to, you can run:
3. Conversely, if you have a git commit in progress, running git-annex may
complain that the index is locked, though this will not prevent it from
working.
git update-index -q --refresh $file
4. When an operation such as a checkout or merge needs to update a large
number of unlocked files, it can become slow. So can be `git add` of
a large number of files (`git annex add` is faster).
(The technical reasons behind these imperfections are explained in
detail in [[todo/git_smudge_clean_interface_suboptiomal]].)
## using less disk space
@ -166,15 +171,6 @@ match the new setting:
git annex fix
Unfortunately, git's smudge interface does not let git-annex honor
the annex.thin configuration when git is checking out a file.
So, using `git checkout` to check out a different branch, or even
`git merge` can result in some non-thin files making their way into the
working tree, and using more disk space. A warning will be printed out in
this situation. You can always run `git annex fix` to re-thin such files.
## annex.thin tradeoffs
[[!template id=note text="""
When a [[direct_mode]] repository is upgraded, annex.thin is automatically
set, because direct mode made the same single-copy tradeoff.