lfs: add user and admin docs (#6158)

5 files changed, 52 insertions, 2 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 180d86d2..ad1662d6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,7 @@ All notable changes to Gogs are documented in this file.
 
 ### Added
 
+- Support for Git LFS, you can read documentation for both [user](https://github.com/gogs/gogs/blob/master/docs/user/lfs.md) and [admin](https://github.com/gogs/gogs/blob/master/docs/admin/lfs.md). [#1322](https://github.com/gogs/gogs/issues/1322)
 - Allow admin to remove observers from the repository. [#5803](https://github.com/gogs/gogs/pull/5803)
 - Use `Last-Modified` HTTP header for raw files. [#5811](https://github.com/gogs/gogs/issues/5811)
 - Support syntax highlighting for SAS code files (i.e. `.r`, `.sas`, `.tex`, `.yaml`). [#5856](https://github.com/gogs/gogs/pull/5856)
diff --git a/README.md b/README.md
index a8e9d8ca..0f393176 100644
--- a/README.md
+++ b/README.md
@@ -26,7 +26,7 @@ The Gogs (`/gɑgz/`) project aims to build a simple, stable and extensible self-
 - Access repositories via SSH, HTTP and HTTPS protocols.
 - User, organization and repository management.
 - Repository and organization webhooks, including Slack, Discord and Dingtalk.
-- Repository Git hooks and deploy keys.
+- Repository Git hooks, deploy keys and Git LFS.
 - Repository issues, pull requests, wiki, protected branches and collaboration.
 - Migrate and mirror repositories with wiki from other code hosts.
 - Web editor for quick editing repository files and wiki.
diff --git a/README_ZH.md b/README_ZH.md
index a933f14e..de3cc874 100644
--- a/README_ZH.md
+++ b/README_ZH.md
@@ -22,7 +22,7 @@ Gogs（`/gɑgz/`）项目旨在打造一个以最简便的方式搭建简单、�
 - 通过 SSH、HTTP 和 HTTPS 协议操作仓库
 - 管理用户、组织和仓库
 - 仓库和组织级 Webhook，包括 Slack、Discord 和钉钉
-- 仓库 Git 钩子和部署密钥
+- 仓库 Git 钩子、部署密钥和 Git LFS
 - 仓库工单（Issue）、合并请求（Pull Request）、Wiki、保护分支和多人协作
 - 从其它代码平台迁移和镜像仓库以及 Wiki
 - 在线编辑仓库文件和 Wiki
diff --git a/docs/admin/lfs.md b/docs/admin/lfs.md
new file mode 100644
index 00000000..143552ec
--- /dev/null
+++ b/docs/admin/lfs.md
@@ -0,0 +1,21 @@
+# Configuring Git Large File Storage (LFS)
+
+> NOTE: Git LFS is supported in Gogs starting with version 0.12.
+
+Git LFS works out of box with default configuration for any supported versions.
+
+## Known limitations
+
+- Only local storage is supported (i.e. all LFS objects are stored on the same server where Gogs runs), support of Object Storage Service like Amazon S3 is being tracked in [#6065](https://github.com/gogs/gogs/issues/6065).
+
+## Configuration
+
+All configuration options for Git LFS are located in [`[lfs]` section](https://github.com/gogs/gogs/blob/44ea9604ed7440c2cf1105d965c2429ee225e8f6/conf/app.ini#L266-L270):
+
+```ini
+[lfs]
+; The storage backend for uploading new objects.
+STORAGE = local
+; The root path to store LFS objects on local file system.
+OBJECTS_PATH = data/lfs-objects
+```
diff --git a/docs/user/lfs.md b/docs/user/lfs.md
new file mode 100644
index 00000000..f89730b6
--- /dev/null
+++ b/docs/user/lfs.md
@@ -0,0 +1,28 @@
+# Git Large File Storage (LFS)
+
+> This document is driven from https://docs.gitlab.com/ee/topics/git/lfs/.
+
+Managing large binaries in Git repositories is challenging, that is why Git LFS was developed for, to manage large files.
+
+## How it works
+
+Git LFS client talks with the Gogs server over HTTP/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.
+
+## Server configuration
+
+Please refer to [Configuring Git Large File Storage (LFS)](../admin/lfs.md).
+
+## Requirements
+
+- Git LFS is supported in Gogs starting with version 0.12.
+- [Git LFS client](https://git-lfs.github.com/) version 1.0.1 and up.
+
+## Known limitations
+
+- When SSH is set as a remote, Git LFS objects still go through HTTP/HTTPS.
+- Any Git LFS request will ask for HTTP/HTTPS credentials to be provided so a good Git credentials store is recommended.
+- File locking is not supported, and is being tracked in [#6064](https://github.com/gogs/gogs/issues/6064).
+
+## Using Git LFS
+
+Git LFS endpoints in a Gogs server can be automatically discovered by the Git LFS client, therefore you do not need to configure anything upfront for using it. Please walk through official [Git LFS Tutorial](https://github.com/git-lfs/git-lfs/wiki/Tutorial) to get started.