Commit f84fb819 authored by Dmitriy Zaporozhets's avatar Dmitriy Zaporozhets

Merge branch 'required_version_and_docs_update' into 'master'

Update required version of lfs client and separate the docs for users and admins.



See merge request !1855
parents 091b879c 7ac112d8
...@@ -50,6 +50,7 @@ ...@@ -50,6 +50,7 @@
- [Welcome message](customization/welcome_message.md) Add a custom welcome message to the sign-in page. - [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. - [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. - [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 ## Contributor documentation
......
...@@ -17,3 +17,4 @@ ...@@ -17,3 +17,4 @@
- [Milestones](milestones.md) - [Milestones](milestones.md)
- [Merge Requests](merge_requests.md) - [Merge Requests](merge_requests.md)
- ["Work In Progress" Merge Requests](wip_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)
# 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. ...@@ -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. 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. Git LFS makes this simpler for the end user by removing the requirement to learn new commands.
<!-- more -->
## How it works ## How it works
Git LFS client talks with the GitLab server over HTTPS. It uses HTTP Basic Authentication to authorize client requests. 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. Once the request is authorized, Git LFS client receives instructions from where to fetch or where to push the large file.
## Requirements ## GitLab server configuration
* 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 Documentation for GitLab instance administrators is under [LFS administration doc](lfs_administration.md).
* Changing the location of LFS object storage
#### Omnibus packages ## Requirements
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 * Git LFS is supported in GitLab starting with version 8.2
lfs: * [Git LFS client](https://git-lfs.github.com) version 1.0.1 and up
enabled: false
storage_path: /mnt/storage/lfs-objects
```
## Known limitations ## 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 * 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 * 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)
* 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)
## Using Git LFS ## Using Git LFS
...@@ -83,6 +55,11 @@ Cloning the repository works the same as before. Git automatically detects the L ...@@ -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 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 ## Troubleshooting
...@@ -90,17 +67,31 @@ git clone git@gitlab.example.com:group/project.git ...@@ -90,17 +67,31 @@ git clone git@gitlab.example.com:group/project.git
There are a couple of reasons why this error can occur: 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 if you have permissions to push to the project or fetch from the project.
Check the version of Git LFS on the client machine with `git lfs version`. Only version 0.6.0 and newer are supported. * Project is not allowed to access the LFS object
* Project is using deprecated LFS API LFS object you are trying to push to the project or fetch from the project is not available to the project anymore.
Probably the object was removed from the server.
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. * Local git repository is using deprecated LFS API
### Invalid status for <url> : 501 ### 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 ### getsockopt: connection refused
...@@ -132,4 +123,4 @@ This will remember the credentials for an hour after which Git operations will r ...@@ -132,4 +123,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. 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).
\ No newline at end of file
...@@ -57,7 +57,7 @@ module Gitlab ...@@ -57,7 +57,7 @@ module Gitlab
501, 501,
{ "Content-Type" => "application/json; charset=utf-8" }, { "Content-Type" => "application/json; charset=utf-8" },
[JSON.dump({ [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", 'documentation_url' => "#{Gitlab.config.gitlab.url}/help",
})] })]
] ]
......
...@@ -26,7 +26,7 @@ describe Gitlab::Lfs::Router do ...@@ -26,7 +26,7 @@ describe Gitlab::Lfs::Router do
let(:sample_oid) { "b68143e6463773b1b6c6fd009a76c32aeec041faff32ba2ed42fd7f708a17f80" } let(:sample_oid) { "b68143e6463773b1b6c6fd009a76c32aeec041faff32ba2ed42fd7f708a17f80" }
let(:sample_size) { 499013 } 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\"}"]]} 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 describe 'when lfs is disabled' do
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment