2020-10-24 23:57:45 +05:30
---
stage: Create
group: Source Code
2021-02-22 17:27:13 +05:30
info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments"
2020-10-24 23:57:45 +05:30
type: reference, howto
---
2021-03-11 19:13:27 +05:30
# Migration guide from Git Annex to Git LFS **(FREE)**
2020-04-22 19:07:51 +05:30
2021-02-22 17:27:13 +05:30
WARNING:
2020-06-23 00:09:42 +05:30
Git Annex support [has been removed ](https://gitlab.com/gitlab-org/gitlab/-/issues/1648 ) in GitLab Enterprise
2020-04-22 19:07:51 +05:30
Edition 9.0 (2017/03/22).
2020-05-24 23:13:21 +05:30
Both [Git Annex ](http://git-annex.branchable.com/ ) and [Git LFS ](https://git-lfs.github.com/ ) are tools to manage large files in Git.
2020-04-22 19:07:51 +05:30
## History
2020-05-24 23:13:21 +05:30
Git Annex [was introduced in GitLab Enterprise Edition 7.8 ](https://about.gitlab.com/blog/2015/02/17/gitlab-annex-solves-the-problem-of-versioning-large-binaries-with-git/ ), at a time
2020-04-22 19:07:51 +05:30
where Git LFS didn't yet exist. A few months later, GitLab brought support for
2020-05-24 23:13:21 +05:30
Git LFS in [GitLab 8.2 ](https://about.gitlab.com/blog/2015/11/23/announcing-git-lfs-support-in-gitlab/ ) and is available for both Community and
2020-04-22 19:07:51 +05:30
Enterprise editions.
## Differences between Git Annex and Git LFS
Some items below are general differences between the two protocols and some are
ones that GitLab developed.
- Git Annex works only through SSH, whereas Git LFS works both with SSH and HTTPS
(SSH support was added in GitLab 8.12).
- Annex files are stored in a sub-directory of the normal repositories, whereas
LFS files are stored outside of the repositories in a place you can define.
- Git Annex requires a more complex setup, but has much more options than Git
LFS. You can compare the commands each one offers by running `man git-annex`
and `man git-lfs` .
2021-02-22 17:27:13 +05:30
- Annex files cannot be browsed directly in the GitLab interface, whereas LFS
2020-04-22 19:07:51 +05:30
files can.
## Migration steps
2021-03-11 19:13:27 +05:30
Git Annex files are stored in a sub-directory of the normal repositories
(`.git/annex/objects`) and LFS files are stored outside of the repositories.
The two aren't compatible as they are using a different scheme. Therefore, the
2020-04-22 19:07:51 +05:30
migration has to be done manually per repository.
There are basically two steps you need to take in order to migrate from Git
Annex to Git LFS.
### TL; DR
If you know what you are doing and want to skip the reading, this is what you
need to do (we assume you have [git-annex enabled ](../../../administration/git_annex.md#using-gitlab-git-annex ) in your
repository and that you have made backups in case something goes wrong).
Fire up a terminal, navigate to your Git repository and:
1. Disable `git-annex` :
```shell
git annex sync --content
git annex direct
git annex uninit
git annex indirect
```
1. Enable `git-lfs` :
```shell
git lfs install
git lfs track < files >
git add .
git commit -m "commit message"
git push
```
2021-03-08 18:12:59 +05:30
### Disabling Git Annex in your repository
2020-04-22 19:07:51 +05:30
Before changing anything, make sure you have a backup of your repository first.
2021-03-11 19:13:27 +05:30
There are a couple of ways to do that, but you can clone it to another
2020-04-22 19:07:51 +05:30
local path and maybe push it to GitLab if you want a remote backup as well.
2021-03-11 19:13:27 +05:30
A guide on
[how to back up a **git-annex** repository to an external hard drive ](https://www.thomas-krenn.com/en/wiki/Git-annex_Repository_on_an_External_Hard_Drive ) is also available.
2020-04-22 19:07:51 +05:30
2021-03-11 19:13:27 +05:30
Because Annex files are stored as objects with symlinks and cannot be directly
2020-04-22 19:07:51 +05:30
modified, we need to first remove those symlinks.
2021-02-22 17:27:13 +05:30
NOTE:
2020-05-24 23:13:21 +05:30
Make sure the you read about the [`direct` mode ](https://git-annex.branchable.com/direct_mode/ ) as it contains
2021-03-11 19:13:27 +05:30
information that may fit in your use case. The `annex direct` command is
2020-04-22 19:07:51 +05:30
deprecated in Git Annex version 6, so you may need to upgrade your repository
if the server also has Git Annex 6 installed. Read more in the
[Git Annex troubleshooting tips ](../../../administration/git_annex.md#troubleshooting-tips ) section.
1. Backup your repository
```shell
cd repository
git annex sync --content
cd ..
git clone repository repository-backup
cd repository-backup
git annex get
cd ..
```
1. Use `annex direct` :
```shell
cd repository
git annex direct
```
The output should be similar to this:
```shell
commit
On branch master
Your branch is up-to-date with 'origin/master'.
nothing to commit, working tree clean
ok
direct debian.iso ok
direct ok
```
2020-05-24 23:13:21 +05:30
1. Disable Git Annex with [`annex uninit` ](https://git-annex.branchable.com/git-annex-uninit/ ):
2020-04-22 19:07:51 +05:30
```shell
git annex uninit
```
The output should be similar to this:
```shell
unannex debian.iso ok
Deleted branch git-annex (was 2534d2c).
```
2021-03-11 19:13:27 +05:30
This command runs `unannex` on every file in the repository, leaving the original files.
2020-04-22 19:07:51 +05:30
1. Switch back to `indirect` mode:
```shell
git annex indirect
```
The output should be similar to this:
```shell
(merging origin/git-annex into git-annex...)
(recording state in git...)
commit (recording state in git...)
ok
(recording state in git...)
[master fac3194] commit before switching to indirect mode
1 file changed, 1 deletion(-)
delete mode 120000 alpine-virt-3.4.4-x86_64.iso
ok
indirect ok
ok
```
---
At this point, you have two options. Either add, commit and push the files
2021-03-11 19:13:27 +05:30
directly back to GitLab or switch to Git LFS. The LFS switch is described in
2020-04-22 19:07:51 +05:30
the next section.
2021-03-08 18:12:59 +05:30
### Enabling Git LFS in your repository
2020-04-22 19:07:51 +05:30
Git LFS is enabled by default on all GitLab products (GitLab CE, GitLab EE,
GitLab.com), therefore, you don't need to do anything server-side.
1. First, make sure you have `git-lfs` installed locally:
```shell
git lfs help
```
If the terminal doesn't prompt you with a full response on `git-lfs` commands,
2020-05-24 23:13:21 +05:30
[install the Git LFS client ](https://git-lfs.github.com/ ) first.
2020-04-22 19:07:51 +05:30
2020-06-23 00:09:42 +05:30
1. Inside the repository, run the following command to initiate LFS:
2020-04-22 19:07:51 +05:30
```shell
git lfs install
```
1. Enable `git-lfs` for the group of files you want to track. You
can track specific files, all files containing the same extension, or an
entire directory:
```shell
git lfs track images/01.png # per file
git lfs track ** /*.png # per extension
git lfs track images/ # per directory
```
2021-03-11 19:13:27 +05:30
After this, run `git status` to see the `.gitattributes` added
2020-06-23 00:09:42 +05:30
to your repository. It collects all file patterns that you chose to track via
2020-04-22 19:07:51 +05:30
`git-lfs` .
1. Add the files, commit and push them to GitLab:
```shell
git add .
git commit -m "commit message"
git push
```
2021-03-11 19:13:27 +05:30
If your remote is set up with HTTP, you are asked to enter your login
2020-04-22 19:07:51 +05:30
credentials. If you have [2FA enabled ](../../../user/profile/account/two_factor_authentication.md ), make sure to use a
[personal access token ](../../../user/profile/account/two_factor_authentication.md#personal-access-tokens )
instead of your password.
## Removing the Git Annex branches
After the migration finishes successfully, you can remove all `git-annex`
related branches from your repository.
2021-02-22 17:27:13 +05:30
On GitLab, navigate to your project's **Repository > Branches** and delete all
2020-04-22 19:07:51 +05:30
branches created by Git Annex: `git-annex` , and all under `synced/` .
![repository branches ](img/git-annex-branches.png )
You can also do this on the command line with:
```shell
git branch -d synced/master
git branch -d synced/git-annex
git push origin :synced/master
git push origin :synced/git-annex
git push origin :git-annex
git remote prune origin
```
If there are still some Annex objects inside your repository (`.git/annex/`)
or references inside `.git/config` , run `annex uninit` again:
```shell
git annex uninit
```
## Further Reading
2020-05-24 23:13:21 +05:30
- (Blog Post) [Getting Started with Git FLS ](https://about.gitlab.com/blog/2017/01/30/getting-started-with-git-lfs-tutorial/ )
- (Blog Post) [Announcing LFS Support in GitLab ](https://about.gitlab.com/blog/2015/11/23/announcing-git-lfs-support-in-gitlab/ )
- (Blog Post) [GitLab Annex Solves the Problem of Versioning Large Binaries with Git ](https://about.gitlab.com/blog/2015/02/17/gitlab-annex-solves-the-problem-of-versioning-large-binaries-with-git/ )
2021-03-11 19:13:27 +05:30
- [Git Annex ](../../../administration/git_annex.md )
- [Git LFS ](index.md )