Commit 6c62f182 authored by Marin Jankovski's avatar Marin Jankovski
Browse files

Updates to the lfs doc.

parent 83827331f0f3
......@@ -12,7 +12,7 @@ Git LFS makes this simpler for the end user by removing the requirement to learn
## 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/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
......@@ -23,7 +23,7 @@ Once the request is authorized, Git LFS client receives instructions from where
### Configuration
Git LFS objects can be large in size and they are stored on GitLab server storage.
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:
......@@ -49,7 +49,7 @@ In `config/gitlab.yml`:
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
* When SSH is set as a remote, Git LFS objects still go through HTTPS
......@@ -66,8 +66,13 @@ For example, if you want to upload a very large file and check it into your Git
git clone git@gitlab.example.com:group/project.git
git lfs init # initialize the Git LFS project project
git lfs track "*.iso" # select the file extensions that you want to treat as large files
```
Once a certain file extension is marked for tracking as a LFS object you can use Git as usual without having to redo the command to track a file with the same extension:
```bash
cp ~/tmp/debian.iso ./ # copy a large file into the current directory
git add . # add the large file to git annex
git add . # add the large file to the project
git commit -am "Added Debian iso" # commit the file meta data
git push origin master # sync the git repo and large file to the GitLab server
```
......@@ -80,26 +85,32 @@ git lfs fetch debian.iso # download the large file
```
## Troubleshooting tips
## Troubleshooting
### error: Repository or object not found
Few reasons why this error can occur:
There are a couple of reasons why this error can occur:
1. Check the version of Git LFS on the client machine, `git lfs version`. Only version 0.6.0 and up are supported.
1. Check the Git config for traces of deprecated API, `git lfs -l`. If `batch = false` remove the line and try using Git LFS client > 0.6.0
* Wrong version of LFS client used:
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 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
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.
### getsockopt: connection refused
When pushing a LFS object and you receive an error similar to: `Post <URL>/info/lfs/objects/batch: dial tcp IP: getsockopt: connection refused`,
LFS client is trying to reach GitLab through HTTPS but your GitLab is being served on HTTP.
This behaviour is caused by Git LFS using HTTPS connections by default when it doesn't have a `lfsurl` set in the Git config.
If you push a LFS object to a project and you receive an error similar to: `Post <URL>/info/lfs/objects/batch: dial tcp IP: getsockopt: connection refused`,
the LFS client is trying to reach GitLab through HTTPS. However, your GitLab instance is being served on HTTP.
This behaviour is caused by Git LFS using HTTPS connections by default when a `lfsurl` is not set in the Git config.
To go around this issue set the lfs url in git config:
To prevent this from happening, set the lfs url in project Git config:
```bash
......
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