Merge branch 'doc-file-lock-refactor' into 'master'

Refactor file lock documentation

- Add permissions section
- Add example pre-receive hook message
- Replace outdated images

See merge request !541

doc/user/project/file_lock.md

@@ -10,8 +10,8 @@ This feature needs to have a license with the "File Lock" option enabled. If
 you are using Enterprise Edition but you don't see the "Lock" button,
 ask your GitLab administrator. Check GitLab's [pricing page] for more information.
 
-GitLab gives you the ability to lock any file or folder in the repository tree
-reserving you the right to make changes to that file or folder. **Locking only
+GitLab gives you the ability to lock any file or directory in the repository tree
+reserving you the right to make changes to that file or directory. **Locking only
 works for the default branch you have set in the project's settings** (usually
 `master`).
 
@@ -22,45 +22,66 @@ The file locking feature is useful in situations when:
 - Your repository contains binary files in which situation there is no easy
   way to tell the diff between yours and your colleagues' changes.
 
----
-
-If you lock a file or folder, then you are the only one who can push changes to
-the repository where the locked objects are located. Locked folders are locked
-recursively.
+Locked directories are locked recursively, which means that everything that
+lies under them is also locked.
 
-Locks can be created by any person who has [push access] to the repository; i.e.,
-developer and higher level. Any user with master permissions can remove any
-lock, no matter who is its author.
+## Permissions on file locking
 
-## Locking
+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.
 
-To lock a file, navigate to the repository tree under the **Code > Files** tab,
+Locks can be created by any person who has [push access] to the repository; i.e.,
+Developer and higher level, and can be removed solely by their author and any
+user with Master permissions and above.
+
+If a file is locked and you are not the author of its locked state, a
+pre-receive hook will reject your changes when you try to push. In the
+following example, a user who has no permissions on the locked `.gitignore`
+file will see the message below:
+
+```bash
+Counting objects: 3, done.
+Delta compression using up to 4 threads.
+Compressing objects: 100% (3/3), done.
+Writing objects: 100% (3/3), 320 bytes | 0 bytes/s, done.
+Total 3 (delta 1), reused 0 (delta 0)
+remote: GitLab: The path '.gitignore' is locked by TheDude
+To https://example.com/gitlab-org/gitlab-ce.git
+ ! [remote rejected] master -> master (pre-receive hook declined)
+ error: failed to push some refs to 'https://example.com/gitlab-org/gitlab-ce.git'
+```
+
+## Locking a file or a directory
+
+To lock a file, navigate to the repository tree under the **Repository > Files** tab,
 pick the file you want to lock and hit the "Lock" button.
 
 ![Locking file](img/file_lock.png)
 
 ---
 
-To lock an entire folder look for the "Lock" link next to "History".
+To lock an entire directory, look for the "Lock" link next to "History".
 
-![Locking folder](img/file_lock_folders.png)
+![Locking directory](img/file_lock_folders.png)
 
 ---
 
-After you lock a file or folder, it will appear as locked in the repository
+After you lock a file or directory, it will appear as locked in the repository
 view.
 
 ![Repository view](img/file_lock_repository_view.png)
 
----
+## Unlocking a file or a directory
 
-To unlock it follow the same procedure or see the following section.
+To unlock a file or a directory, follow the same procedure as when you locked
+them. For a detailed view of every existing lock, see the next section on
+"Viewing and managing existing locks".
 
-## Viewing/Managing existing locks
+## Viewing and managing existing locks
 
 To view or manage every existing lock, navigate to the
-**Project > Code > Locked Files** section. Only the user that created the lock
-and Masters are able to remove the locked objects.
+**Project > Repository > Locked Files** area. There, you can view all existing
+locks and [remove the ones you have permission for](#permissions-on-file-locking).
 
 ![Locked Files](img/file_lock_list.png)