Update required version of lfs client and separate the docs for users and admins.
This commit is contained in:
Marin Jankovski
parent
807c1a993d
commit
899807f604
6 changed files with 76 additions and 43 deletions
|
|
@ -50,6 +50,7 @@
|
|||
- [Welcome message](customization/welcome_message.md) Add a custom welcome message to the sign-in page.
|
||||
- [Reply by email](incoming_email/README.md) Allow users to comment on issues and merge requests by replying to notification emails.
|
||||
- [Migrate GitLab CI to CE/EE](migrate_ci_to_ce/README.md) Follow this guide to migrate your existing GitLab CI data to GitLab CE/EE.
|
||||
- [Git LFS configuration](workflow/lfs/lfs_administration.md)
|
||||
|
||||
## Contributor documentation
|
||||
|
||||
|
|
|
|||
|
|
@ -17,3 +17,4 @@
|
|||
- [Milestones](milestones.md)
|
||||
- [Merge Requests](merge_requests.md)
|
||||
- ["Work In Progress" Merge Requests](wip_merge_requests.md)
|
||||
- [Manage large binaries with Git LFS](lfs/manage_large_binaries_with_git_lfs.md)
|
||||
|
|
|
|||
41
doc/workflow/lfs/lfs_administration.md
Normal file
41
doc/workflow/lfs/lfs_administration.md
Normal file
|
|
@ -0,0 +1,41 @@
|
|||
## GitLab Git LFS Administration
|
||||
|
||||
Documentation on how to use Git LFS are under [Managing large binary files with Git LFS doc](manage_large_binaries_with_git_lfs.md).
|
||||
|
||||
## Requirements
|
||||
|
||||
* Git LFS is supported in GitLab starting with version 8.2.
|
||||
* Users need to install [Git LFS client](https://git-lfs.github.com) version 1.0.1 and up
|
||||
|
||||
## Configuration
|
||||
|
||||
Git LFS objects can be large in size. By default, they are stored on the server GitLab is installed on.
|
||||
|
||||
There are two configuration options to help GitLab server administrators:
|
||||
|
||||
* Enabling/disabling Git LFS support
|
||||
* Changing the location of LFS object storage
|
||||
|
||||
### Omnibus packages
|
||||
|
||||
In `/etc/gitlab/gitlab.rb`:
|
||||
|
||||
```ruby
|
||||
gitlab_rails['lfs_enabled'] = false
|
||||
gitlab_rails['lfs_storage_path'] = "/mnt/storage/lfs-objects"
|
||||
```
|
||||
|
||||
### Installations from source
|
||||
|
||||
In `config/gitlab.yml`:
|
||||
|
||||
```yaml
|
||||
lfs:
|
||||
enabled: false
|
||||
storage_path: /mnt/storage/lfs-objects
|
||||
```
|
||||
|
||||
## Known limitations
|
||||
|
||||
* Currently, storing GitLab Git LFS objects on a non-local storage (like S3 buckets) is not supported
|
||||
* Currently, removing LFS objects from GitLab Git LFS storage is not supported
|
||||
|
|
@ -7,55 +7,27 @@ GitLab already supports [managing large files with git annex](http://doc.gitlab.
|
|||
environments it is not always convenient to use different commands to differentiate between the large files and regular ones.
|
||||
|
||||
Git LFS makes this simpler for the end user by removing the requirement to learn new commands.
|
||||
<!-- more -->
|
||||
|
||||
## How it works
|
||||
|
||||
Git LFS client talks with the GitLab server over HTTPS. It uses HTTP Basic Authentication to authorize client requests.
|
||||
Once the request is authorized, Git LFS client receives instructions from where to fetch or where to push the large file.
|
||||
|
||||
## GitLab server configuration
|
||||
|
||||
Documentation for GitLab instance administrators is under [LFS administration doc](lfs_administration.md).
|
||||
|
||||
## Requirements
|
||||
|
||||
* Git LFS is supported in GitLab starting with version 8.2
|
||||
* Git LFS [client](https://git-lfs.github.com) version 0.6.0 and up
|
||||
|
||||
## GitLab and Git LFS
|
||||
|
||||
### Configuration
|
||||
|
||||
Git LFS objects can be large in size. By default, they are stored on the server GitLab is installed on.
|
||||
|
||||
There are two configuration options to help GitLab server administrators:
|
||||
|
||||
* Enabling/disabling Git LFS support
|
||||
* Changing the location of LFS object storage
|
||||
|
||||
#### Omnibus packages
|
||||
|
||||
In `/etc/gitlab/gitlab.rb`:
|
||||
|
||||
```ruby
|
||||
gitlab_rails['lfs_enabled'] = false
|
||||
gitlab_rails['lfs_storage_path'] = "/mnt/storage/lfs-objects"
|
||||
```
|
||||
|
||||
#### Installations from source
|
||||
|
||||
In `config/gitlab.yml`:
|
||||
|
||||
```yaml
|
||||
lfs:
|
||||
enabled: false
|
||||
storage_path: /mnt/storage/lfs-objects
|
||||
```
|
||||
* [Git LFS client](https://git-lfs.github.com) version 1.0.1 and up
|
||||
|
||||
## Known limitations
|
||||
|
||||
* Git LFS v1 original API is not supported since it was deprecated early in LFS development, starting with Git LFS version 0.6.0
|
||||
* Git LFS v1 original API is not supported since it was deprecated early in LFS development
|
||||
* When SSH is set as a remote, Git LFS objects still go through HTTPS
|
||||
* Any Git LFS request will ask for HTTPS credentials to be provided so good Git credentials store is recommended
|
||||
* Currently, storing GitLab Git LFS objects on a non-local storage (like S3 buckets) is not supported
|
||||
* Git LFS always assumes HTTPS so if you have GitLab server on HTTP you will have to add the URL to Git config manually (see #troubleshooting-tips)
|
||||
* Git LFS always assumes HTTPS so if you have GitLab server on HTTP you will have to add the URL to Git config manually (see #troubleshooting)
|
||||
|
||||
## Using Git LFS
|
||||
|
||||
|
|
@ -83,6 +55,11 @@ Cloning the repository works the same as before. Git automatically detects the L
|
|||
git clone git@gitlab.example.com:group/project.git
|
||||
```
|
||||
|
||||
If you already cloned the repository and you want to get the latest LFS object that are on the remote repository, eg. from branch `master`:
|
||||
|
||||
```bash
|
||||
git lfs fetch master
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
|
|
@ -90,17 +67,30 @@ git clone git@gitlab.example.com:group/project.git
|
|||
|
||||
There are a couple of reasons why this error can occur:
|
||||
|
||||
* Wrong version of LFS client used:
|
||||
* You don't have permissions to access certain LFS object
|
||||
|
||||
Check the version of Git LFS on the client machine with `git lfs version`. Only version 0.6.0 and newer are supported.
|
||||
Check if you have permissions to push to the project or fetch from the project.
|
||||
|
||||
* Project is not allowed to access the LFS object
|
||||
|
||||
Check if the LFS object you are trying to push to the project or fetch from the project is available to the project.
|
||||
|
||||
* Project is using deprecated LFS API
|
||||
|
||||
Check the Git config of the project for traces of deprecated API with `git lfs -l`. If `batch = false` is set in the config, remove the line and try using Git LFS client newer than 0.6.0.
|
||||
|
||||
### Invalid status for <url> : 501
|
||||
|
||||
When attempting to push a LFS object to a GitLab server that doesn't have Git LFS support enabled, server will return status `error 501`. Check with your GitLab administrator why Git LFS is not enabled on the server. See [Configuration section](#configuration) for instructions on how to enable LFS support.
|
||||
Git LFS will log the failures into a log file.
|
||||
To view this log file, while in project directory:
|
||||
|
||||
```bash
|
||||
git lfs logs last
|
||||
```
|
||||
|
||||
If the status `error 501` is shown, it is because:
|
||||
|
||||
* Git LFS support is not enabled on the GitLab server. Check with your GitLab administrator why Git LFS is not enabled on the server. See [LFS administration documentation](lfs_administration.md) for instructions on how to enable LFS support.
|
||||
|
||||
* Git LFS client version is not supported by GitLab server. Check your Git LFS version with `git lfs version`. Check the Git config of the project for traces of deprecated API with `git lfs -l`. If `batch = false` is set in the config, remove the line and try to update your Git LFS client. Only version 1.0.1 and newer are supported.
|
||||
|
||||
### getsockopt: connection refused
|
||||
|
||||
|
|
@ -132,4 +122,4 @@ This will remember the credentials for an hour after which Git operations will r
|
|||
|
||||
If you are using OS X you can use `osxkeychain` to store and encrypt your credentials. For Windows, `wincred` is available.
|
||||
|
||||
More details about various methods of storing the user credentials can be found on [Git Credential Storage documentation](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage)
|
||||
More details about various methods of storing the user credentials can be found on [Git Credential Storage documentation](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage).
|
||||
|
|
@ -57,7 +57,7 @@ module Gitlab
|
|||
501,
|
||||
{ "Content-Type" => "application/json; charset=utf-8" },
|
||||
[JSON.dump({
|
||||
'message' => 'Server supports batch API only, please update your Git LFS client to version 0.6.0 and up.',
|
||||
'message' => 'Server supports batch API only, please update your Git LFS client to version 1.0.1 and up.',
|
||||
'documentation_url' => "#{Gitlab.config.gitlab.url}/help",
|
||||
})]
|
||||
]
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ describe Gitlab::Lfs::Router do
|
|||
|
||||
let(:sample_oid) { "b68143e6463773b1b6c6fd009a76c32aeec041faff32ba2ed42fd7f708a17f80" }
|
||||
let(:sample_size) { 499013 }
|
||||
let(:respond_with_deprecated) {[ 501, { "Content-Type"=>"application/json; charset=utf-8" }, ["{\"message\":\"Server supports batch API only, please update your Git LFS client to version 0.6.0 and up.\",\"documentation_url\":\"#{Gitlab.config.gitlab.url}/help\"}"]]}
|
||||
let(:respond_with_deprecated) {[ 501, { "Content-Type"=>"application/json; charset=utf-8" }, ["{\"message\":\"Server supports batch API only, please update your Git LFS client to version 1.0.1 and up.\",\"documentation_url\":\"#{Gitlab.config.gitlab.url}/help\"}"]]}
|
||||
let(:respond_with_disabled) {[ 501, { "Content-Type"=>"application/json; charset=utf-8" }, ["{\"message\":\"Git LFS is not enabled on this GitLab server, contact your admin.\",\"documentation_url\":\"#{Gitlab.config.gitlab.url}/help\"}"]]}
|
||||
|
||||
describe 'when lfs is disabled' do
|
||||
|
|
|
|||
Loading…
Reference in a new issue