git-annex/ git-annex-unlock

# NAME

git-annex unlock - unlock files for modification

# SYNOPSIS

git annex unlock `[path ...]`

# DESCRIPTION

Normally, the content of annexed files is protected from being changed. Unlocking an annexed file allows it to be modified. When no files are specified, all annexed files in the current directory are unlocked.

Unlocking a file changes how it is stored in the git repository (from a symlink to a pointer file), so this command will make a change that you can commit.

The content of an unlocked file is still stored in git-annex, not git, and when you commit modifications to the file, the modifications will also be stored in git-annex, with only the pointer file stored in git.

If you use `git add` to add a file to the annex, it will be added in unlocked form from the beginning. This allows workflows where a file starts out unlocked, is modified as necessary, and is locked once it reaches its final version.

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; this makes a hard link to the content be made instead of a copy. (Only 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.

# EXAMPLES

    # git annex unlock disk-image
    # git commit -m "unlocked to allow VM to make changes as it runs"

    # git annex unlock photo.jpg
    # gimp photo.jpg
    # git commit photo.jpg -m "redeye removal"
    # gimp photo.jpg
    # git commit photo.jpg -m "fix oversaturation"
    # git annex lock photo.jpg

# OPTIONS

- file matching options

  The git-annex-matching-options(1) can be used to specify files to unlock.

- `--json`

  Enable JSON output. This is intended to be parsed by programs that use git-annex. Each line of output is a JSON object.

- `--json-error-messages`

  Messages that would normally be output to standard error are included in the JSON instead.

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

# SEE ALSO

git-annex(1)

git-annex-edit(1)

git-annex-add(1)

git-annex-lock(1)

# AUTHOR

Joey Hess id@joeyh.name

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

clarifying unlocked files
Does the locked/unlocked state apply to one particular path within the repo, or to a particular key? Can the same key be used by both a locked and an unlocked file?
Comment by Ilya_Shlyakhter — Wed Oct 29 14:05:27 2025
Are my unlocked, annexed files still safe?

I want to double-check something: if I've annexed and committed files, I believe they are safely stored in git-annex even if I unlock them (as long as I don't use `--thin`). If I annex copies of the the same file, annex will only store it once, and use a symlink for the two original files. But if I unlock them, I can edit them independently.

Basically, unlock gives me an editable copy of the file - but I always have the original version, and can revert or check it out if I need to. Is that correct?

Comment by pat — Wed Oct 29 14:05:27 2025
re: issue with example

`git-annex lock` wouldn't erase any modifications, but it would fail due to the file being modified. Fixed the example to use `git-annex add` before locking.

Comment by joey — Wed Oct 29 14:05:27 2025
issue with example

In the example, wouldn't `git-annex-unlock` erase any edits made in gimp? Was this meant to use `git-annex-add` instead?

# EXAMPLES

    # git annex unlock photo.jpg
    # gimp photo.jpg
    # git annex lock photo.jpg
    # git commit -m "redeye removal"

Comment by Ilya_Shlyakhter — Wed Oct 29 14:05:27 2025
Re: Move file from git annex to just git in one commit

See largefiles, it has recipes for conversion from annex to git and from git to annex.

Comment by joey — Wed Oct 29 14:05:27 2025
Move file from git annex to just git in one commit

Hello. I'd like to know, how could I move back a file managed by git annex to a normal file (for example, say I added by mistake a text file in it). For now, I do `git unlock MYFILE`, then I remove the file from git: `git rm --cached MYFILE`, and `git commit -am 'Remove file'`, and finally I add back the file, `git add MYFILE && git commit -am 'File added back in git'`. However, this creates two commits, which is a bit annoying and leave the feeling that the file has been removed while it was just a kind of modification. How could I do that in less commands, and with a single commit? Thanks!

Comment by tobiasBora — Wed Oct 29 14:05:27 2025
comment 3

The page about unlocked files says:

> setting annex.thin only has any effect on systems that support hard links. It is supported on Windows, but not on FAT filesystems.

Comment by chocolate.camera — Wed Oct 29 14:05:27 2025
comment 2

Yes, if you don't want the copy set annex.thin as documented on the man page.

Comment by joey — Wed Oct 29 14:05:27 2025
Re: We don’t need a 'git annex lock' after a 'git annex add', right?

Well spotted. `git-annex add` defaults to adding files locked, even when adding what was an unlocked file before.

I've improved the example.

Comment by joey — Wed Oct 29 14:05:27 2025
We don’t need a 'git annex lock' after a 'git annex add', right?

Hi there!

I'm learning how to use `unlock`, and I'm relatively new to `git-annex`.

I think I’ve understood the concept behind this feature, but I don’t get why, in the example, the `git annex lock` command is used after `git annex add`:

    git annex unlock photo.jpg
    gimp photo.jpg
    git annex add photo.jpg
    git annex lock photo.jpg   <------ This one
    git commit -m "redeye removal"

Isn’t the file already locked by the `git annex add` ?

Thank you in advance.

Comment by Cletip — Wed Oct 29 14:05:27 2025
re: clarifying unlocked files

@Ilya_Shlyakhter:

> Does the locked/unlocked state apply to one particular path within the repo, or to a particular key?

A particular path.

> Can the same key be used by both a locked and an unlocked file?

Yes.

Comment by kyle — Wed Oct 29 14:05:27 2025
re: Are my unlocked, annexed files still safe?

@pat:

> Basically, unlock gives me an editable copy of the file - but I always have the original version, and can revert or check it out if I need to. Is that correct?

Yes, it's a copy as long as you don't set `annex.thin=true` (as you mention). Just as with locked files, though, you may not be able to get the content back from an earlier version if you've dropped unused content.

Comment by kyle — Wed Oct 29 14:05:27 2025
comment 1

> Normally, unlocking a file requires a copy to be made of its content, so that its original content is preserved

Does that imply than, on v7 in a file system that does not support hard links such as FAT32, `git annex adjust --unlock` would effectively be creating a duplicate of all files via cp (which is incredibly costly time-wise specially for big repos and huge files) and would effectively double the size it occupies?

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