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

doc/README.md

@@ -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
 

doc/workflow/README.md

@@ -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)

doc/workflow/lfs/lfs_administration.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

doc/workflow/git_lfs.md → doc/workflow/lfs/manage_large_binaries_with_git_lfs.md

@@ -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.
 
-## 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:
+## GitLab server configuration
 
-* Enabling/disabling Git LFS support
-* Changing the location of LFS object storage
+Documentation for GitLab instance administrators is under [LFS administration doc](lfs_administration.md).
 
-#### 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`:
+## Requirements
 
-```yaml
-  lfs:
-    enabled: false
-    storage_path: /mnt/storage/lfs-objects
-```
+* Git LFS is supported in GitLab starting with version 8.2
+* [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,31 @@ 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 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
 
-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 +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.
 
-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
+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).

lib/gitlab/lfs/response.rb

@@ -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",
           })]
         ]

spec/lib/gitlab/lfs/lfs_router_spec.rb

@@ -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