Review file locking refactor

Brief rewording, achors fix, metadata

doc/topics/git/lfs/index.md

@@ -109,9 +109,7 @@ To remove objects from LFS:
 
 ## File Locking
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35856) in GitLab 10.5.
-
-TODO
+See the documentation on [File Locking](../../../user/project/file_lock.md).
 
 ## Troubleshooting
 

doc/user/permissions.md

@@ -222,7 +222,7 @@ to learn more.
 
 The user that locks a file or directory is the only one that can edit and push their changes back to the repository where the locked objects are located.
 
-Read through the documentation on [permissions for File Locking](project/file_lock.md#permissions-on-file-locking) to learn more.
+Read through the documentation on [permissions for File Locking](project/file_lock.md#permissions) to learn more.
 
 ### Confidential Issues permissions
 

doc/user/project/file_lock.md

-# File Locking
+---
+stage: Create
+group: Source Code
+info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers"
+type: reference, howto
+last_updated: 2020-08-10
+---
 
-When working with binary files in a collaborative project, file locking helps
-prevent multiple people changing the same file at the same time. Branching works
-for source code and plain text because different versions can be merged
-together, but this does not work for binary files.
+# File Locking **(CORE)**
+
+Preventing wasted work caused by unresolvable merge conflicts requires
+a different way of working. This means explicitly requesting write permissions,
+and verifying no one else is editing the same file before you start.
+
+Although branching strategies usually work well enough for source code and
+plain text because different versions can be merged together, they do not work
+for binary files.
+
+When file locking is setup, lockable files are **read only** by default.
 
 When a file is locked, only the user who locked the file may modify it. This
 user is said to "hold the lock" or have "taken the lock", since only one user
-may lock a file at a time. When a file or directory is unlocked, the user is
+can lock a file at a time. When a file or directory is unlocked, the user is
 said to have "released the lock".
 
 GitLab supports two different modes of file locking:
 
-- [Exclusive locks](#exclusive-file-locks) for binary files, to
-  prevent locked files being modified on any branch.
-- [Default branch locks](#default-branch-file-and-directory-locks) to prevent
-  locked files and directories being modified on the default branch.
+- [Exclusive file locks](#exclusive-file-locks) for binary files: done **through
+  the command line** with Git LFS and `.gitattributes`, it prevents locked
+  files from being modified on any branch. **(CORE)**
+- [Default branch locks](#default-branch-file-and-directory-locks-premium): done
+  **through the GitLab UI**, it prevents locked files and directories being
+  modified on the default branch. **(PREMIUM)**
 
 ## Permissions
 
+Locks can be created by any person who has at least
+[Developer permissions](../permissions.md) to the repository.
+
 Only the user who locked the file or directory can edit locked files. Others
-users will be prevented from modifying locked files through by pushing, merging
+users will be prevented from modifying locked files by pushing, merging,
 or any other means, and will be shown an error like: `The path '.gitignore' is
-locked by Administrator`
-
-Locks can be created by any person who has [push access](../permissions.md) to
-the repository, Developer permissions and above.
-
-Locks can be only be removed by their author, or any user with Maintainer
-permissions and above.
+locked by Administrator`.
 
-## Exclusive file locks **(CORE)**
+## Exclusive file locks
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35856) in GitLab 10.5.
 
-Preventing wasted work caused by unresolvable merge conflicts prevents requires
-a different way of working. This means explicitly requesting write permissions,
-and verifying no one else is editing the same file before editing begins.
+This process allows you to lock single files or file extensions and it is
+done through the command line. It doesn't require GitLab paid subscriptions.
 
-When file locking is setup, lockable files are **read only** by default.
+Git LFS is well known for tracking files to reduce the storage of
+Git repositories, but it can also be user for [locking files](https://github.com/git-lfs/git-lfs/wiki/File-Locking).
+This is the method used for Exclusive File Locks.
 
-1. To edit a file, request the lock. This verifies that no one else is editing
-   the file, and prevents anyone else editing the file until you're done.
+### Install Git LFS
 
-   ```shell
-   git lfs lock path/to/file.png
-   ```
+Before getting started, make sure you have [Git LFS installed](../../topics/git/lfs/index.md) in your computer. Open a terminal window and run:
 
-1. When you're done, return the lock. This communicates that you finished
-   editing the file, and allows other people to edit the file.
-
-   ```shell
-   git lfs unlock path/to/file.png
-   ```
-
-TODO: workflow suggestion - don't unlock until the change is in the default
-branch. Maybe this can be a follow up on practical workflows.
-
-NOTE: **Note:**
-Although multi-branch file locks can be created and managed through the Git LFS
-command line interface, file locks can be created for any file.
+```shell
+git-lfs --version
+```
 
-### Getting started (user)
+If it doesn't recognize this command, you'll have to install it. There are
+several [installation methods](https://git-lfs.github.com/) that you can
+choose according to your OS. To install it with Homebrew:
 
-TODO: how do I use file locks on an existing project that someone has already
-setup. E.g. what do I do after running `git clone`
+```shell
+brew install git-lfs
+```
 
-1. Install Git LFS
+Once installed, **open your local repository in a terminal window** and
+install Git LFS in your repo. If you're sure that LFS is already installed,
+you can skip this step. If you're unsure, re-installing it won't do any harm:
 
-   ```shell
-   git lfs install
-   ```
+```shell
+git lfs install
+```
 
-1. Fetch the current file lock status, and update file permissions so that
-   lockable files are read only.
+Check this document to learn more about [using Git LFS](../../topics/git/lfs/index.md#using-git-lfs).
 
-   ```shell
-   git lfs locks
-   git checkout .
-   ```
+### Configure Exclusive File Locks
 
-### Configure lockable files (maintainer)
+You need [Maintainer permissions](../permissions.md) to configure
+Exclusive File Locks for your project through the command line.
 
 The first thing to do before using File Locking is to tell Git LFS which
 kind of files are lockable. The following command will store PNG files
@@ -97,9 +99,9 @@ created or updated with the following content:
 *.png filter=lfs diff=lfs merge=lfs -text lockable
 ```
 
-You can also register a file type as lockable without using LFS
-(In order to be able to lock/unlock a file you need a remote server that implements the LFS File Locking API),
-in order to do that you can edit the `.gitattributes` file manually:
+You can also register a file type as lockable without using LFS (to be able, for example, to lock/unlock a file you need a in a remote server that
+implements the LFS File Locking API). To do that you can edit the
+`.gitattributes` file manually:
 
 ```shell
 *.pdf lockable
@@ -107,50 +109,78 @@ in order to do that you can edit the `.gitattributes` file manually:
 
 After a file type has been registered as lockable, Git LFS will make
 them read-only on the file system automatically. This means you will
-need to lock the file before editing it.
+need to **lock the file before editing it**.
 
-TODO: reminder that `.gitattributes` should be commited to the repo!
+### Lock files
 
-### Managing locked files
+To lock a file with Exclusive File Locking, open a terminal window in your
+repo and:
 
-Once you're ready to edit your file you need to lock it first:
+1. To edit a file, request the lock. This verifies that no one else is editing
+   the file, and prevents anyone else from editing the file until you're done.
 
-```shell
-git lfs lock images/banner.png
-Locked images/banner.png
-```
+   ```shell
+   git lfs lock path/to/file.png
+   ```
 
-This will register the file as locked in your name on the server:
+1. When you're done, return the lock. This communicates that you finished
+   editing the file, and allows other people to edit the file.
 
-```shell
-git lfs locks
-images/banner.png  joe   ID:123
-```
+   ```shell
+   git lfs unlock path/to/file.png
+   ```
 
-Once you have pushed your changes, you can unlock the file so others can
-also edit it:
+   You can also unlock by file ID:
 
-```shell
-git lfs unlock images/banner.png
-```
+   ```shell
+   git lfs unlock --id=123
+   ```
 
-You can also unlock by ID:
+   If for some reason you need to unlock a file that was not locked by
+   yourself, you can use the `--force` flag as long as you have **Maintainer**
+   permissions to the project:
 
-```shell
-git lfs unlock --id=123
-```
+   ```shell
+   git lfs unlock --id=123 --force
+   ```
+
+You can normally push files to GitLab whether they're locked or unlocked.
+Remind that the `.gitattributes` file must also be pushed to the remote repo.
+
+NOTE: **Note:**
+Although multi-branch file locks can be created and managed through the Git LFS
+command line interface, file locks can be created for any file.
+
+### View exclusively-locked files
 
-If for some reason you need to unlock a file that was not locked by you,
-you can use the `--force` flag as long as you have a `maintainer` access on
-the project:
+To list all the files locked with LFS locally, open a terminal window in your
+repo and run:
 
 ```shell
-git lfs unlock --id=123 --force
+git lfs locks
 ```
 
+On the repository file tree, GitLab will display an LFS badge for files
+tracked by Git LFS plus a padlock icon on exclusively-locked files:
+
+![LFS-Locked files](img/lfs_locked_files_v13_2.png)
+
+You can also [view and remove existing locks](#view-and-remove-existing-locks) from the GitLab UI.
+
+NOTE: **Note:**
+When you rename an exclusively-locked file, the lock is lost. You'll have to
+lock it again to keep it locked.
+
+<!-- TODO: workflow suggestion - don't unlock until the change is in the default
+branch. Maybe this can be a follow up on practical workflows.
+ -->
+
 ## Default branch file and directory locks **(PREMIUM)**
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/440) in [GitLab Premium](https://about.gitlab.com/pricing/) 8.9.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/440) in GitLab Enterprise Edition 8.9. Available in [GitLab Premium](https://about.gitlab.com/pricing/).
+
+This process allows you to lock one file at a time through the GitLab UI and
+requires access to [GitLab Premium, GitLab.com Silver](https://about.gitlab.com/pricing/), or higher tiers.
 
 Default branch file and directory locks only apply to the default branch set in
 the project's settings (usually `master`).
@@ -158,7 +188,7 @@ the project's settings (usually `master`).
 Changes to locked files on the default branch will be blocked, including merge
 requests that modify locked files. Unlock the file to allow changes.
 
-### Locking and unlocking a file or a directory
+### Lock a file or a directory
 
 To lock a file:
 
@@ -170,12 +200,13 @@ To lock a file:
 An **Unlock** button will be displayed if the file is already locked, and
 will be disabled if you do not have permission to unlock the file.
 
-If you did not lock the file, hovering your cursor over the button will show who
-locked the file.
+If you did not lock the file, hovering your cursor over the button will show
+who locked the file.
 
-### Viewing and remove existing locks
+### View and remove existing locks
 
 The **Locked Files**, accessed from **Project > Repository** left menu, lists
 all file and directory locks. Locks can be removed by their author, or any user
 with Maintainer permissions and above.
 
+This list shows all the files locked either through LFS or GitLab UI.