| commit | author | age | ||
| 697905 | 1 | ## Configure Git Large File Storage |
| PM | 2 | |
| 3 | Gitblit provides a filestore that supports the [Git Large File Storage (LFS) API](https://git-lfs.github.com/). | |
| 4 | ||
| 5 | ### Server Configuration | |
| 6 | ||
| 7 | Gitblit is configured to work straight away. However you may want to update the following in `gitblit.properties`: | |
| 8 | ||
| 9 | <table class="table"> | |
| 10 | <thead> | |
| 11 | <tr><th>parameter</th><th>value</th><th>description</th></tr> | |
| 12 | </thead> | |
| 13 | <tbody> | |
| 14 | <tr> | |
| 15 | <th>filestore.storageFolder</th><td>${baseFolder}/lfs</td> | |
| 16 | <td>The path on the server where filestore objects are to be saved.</td> | |
| 17 | </tr> | |
| 18 | <tr> | |
| 19 | <th>filestore.maxUploadSize</th><td>-1</td> | |
| 20 | <td>The maximum allowable size that can be uploaded to the filestore. Once a file is uploaded it will be unaffected by later changes in this property. The default of -1 indicates no limits.</td> | |
| 21 | </tr> | |
| 22 | </tbody> | |
| 23 | </table> | |
| 24 | ||
| 25 | ||
| 26 | ### Limitations | |
| 27 | ||
| 28 | Gitblit currently provides a server-only implementation of the opensource Git LFS API. | |
| 29 | ||
| 30 | 1. Files in the filestore are not currently searchable by Lucene. | |
| 31 | 2. Mirroring a repository that uses Git LFS will only mirror the pointer files, not the large files. | |
| 32 | 3. Federation - Only the pointer files, not the large files, are transfered. | |
| 33 | ||
| 34 | Items 2 & 3 are pending [JGit Git LFS client capabilities](https://bugs.eclipse.org/bugs/show_bug.cgi?id=470333). | |
| 35 | ||
| 36 | ||
| 37 | ### How does it work? | |
| 38 | ||
| 39 | 1. Files that should be handled by Git LFS are defined in the `.gitattributes` file. | |
| 40 | 2. Git LFS installs a pre-commit hook when installed `git lfs install`. | |
| 41 | 3. When a commit is made the pre-commit hook replaces the defined Git LFS files with a pointer file containing metadata about the file so that it can be found later. | |
| 42 | 4. When a commit is pushed, the changeset is sent to the git repository and the large files are sent to the filestore. | |
| 43 | ||
| 44 | For further details check out the [Git LFS specification](https://github.com/github/git-lfs/blob/master/docs/spec.md). | |
| 45 | ||
| 46 | ### Convert/Migrate existing repository | |
| 47 | ||
| 48 | It is possible to migrate an existing repository containing large files to one that leverages the filestore. However, commit hash history will be altered. | |
| 49 | ||
| 50 | The following command may be run on a local repository: | |
| 51 | ||
| 52 | git filter-branch --prune-empty --tree-filter ' | |
| 53 | git lfs track "*.docx" "*.pdf" > /dev/null | |
| 54 | git add .gitattributes | |
| 55 | git ls-files | xargs -d "\n" git check-attr filter | grep "filter: lfs" | sed -r "s/(.*): filter: lfs/\1/" | xargs -d "\n" -r bash -c "git rm -f --cached \"\$@\"; git add \"\$@\"" bash \ | |
| 56 | ' --tag-name-filter cat -- --all | |
| 57 | ||
| 58 | ||
| 59 | ### Further Considerations | |
| 60 | ||
| 61 | While [other Git LFS implementations are available](https://github.com/github/git-lfs/wiki/Implementations) as there is no current [JGit LFS client capability](https://bugs.eclipse.org/bugs/show_bug.cgi?id=470333), Gitblit will be unable to access them. | |
