Skip to content

G
gitlab-ce
Commit fc6e83c2 authored by Marcia Ramos's avatar Marcia Ramos
Browse files
Options

Merge branch 'revise-file-locking-documentation' into 'master' 

Refactor file locking docs

See merge request gitlab-org/gitlab!35212
parents 2e5871f3 0f12adfe
Hide whitespace changes
Inline Side-by-side
Showing with 175 additions and 135 deletions
doc/topics/git/lfs/index.md
View file @ fc6e83c2
......@@ -109,71 +109,7 @@ To remove objects from LFS:
## File Locking
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35856) in GitLab 10.5.
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
in LFS and flag them as lockable:
```shell
git lfs track "*.png" --lockable
```
After executing the above command a file named `.gitattributes` will be
created or updated with the following content:
```shell
*.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:
```shell
*.pdf lockable
```
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.
### Managing Locked Files
Once you're ready to edit your file you need to lock it first:
```shell
git lfs lock images/banner.png
Locked images/banner.png
```
This will register the file as locked in your name on the server:
```shell
git lfs locks
images/banner.png joe ID:123
```
Once you have pushed your changes, you can unlock the file so others can
also edit it:
```shell
git lfs unlock images/banner.png
```
You can also unlock by ID:
```shell
git lfs unlock --id=123
```
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:
```shell
git lfs unlock --id=123 --force
```
See the documentation on [File Locking](../../../user/project/file_lock.md).
## Troubleshooting
......
doc/user/permissions.md
View file @ fc6e83c2
......@@ -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
View file @ fc6e83c2
......@@ -3,106 +3,210 @@ 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
---
# File Locking **(PREMIUM)**
# File Locking **(CORE)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/440) in [GitLab Premium](https://about.gitlab.com/pricing/) 8.9.
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.
Working with multiple people on the same file can be a risk. Conflicts when merging a non-text file are hard to overcome and will require a lot of manual work to resolve. File Locking helps you avoid these merge conflicts and better manage your binary files.
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.
With File Locking, you can lock any file or directory, make your changes, and
then unlock it so another member of the team can edit it.
When file locking is setup, lockable files are **read only** by default.
## Overview
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
can lock a file at a time. When a file or directory is unlocked, the user is
said to have "released the lock".
Working with multiple people on the same file can be a risk. Conflicts
when merging a non-text file are hard to overcome and will require a lot
of manual work to resolve. With GitLab Premium, File
Locking helps you avoid merge conflicts and better manage your binary
files by preventing everyone, except you, from modifying a specific file
or entire directory.
GitLab supports two different modes of file locking:
## Use-cases
- [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)**
The file locking feature is useful in situations when:
## Permissions
- Multiple people are working on the same file and you want to avoid merge
conflicts.
- Your repository contains binary files in which situation there is no easy
way to tell the diff between yours and your colleagues' changes.
- Prevent design assets from being overwritten.
Locks can be created by any person who has at least
[Developer permissions](../permissions.md) to the repository.
Locked directories are locked recursively, which means that everything that
lies under them is also locked.
Only the user who locked the file or directory can edit locked files. Others
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`.
## Locking a file or a directory
## Exclusive file locks
NOTE: **Note:**
Locking only works for the default branch you have set in the project's settings
(usually `master`).
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35856) in GitLab 10.5.
To lock a file:
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.
1. Navigate to your project's **Repository > Files**.
1. Pick the file you want to lock.
1. Click the "Lock" button.
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.
![Locking file](img/file_lock.png)
### Install Git LFS
To lock an entire directory, look for the "Lock" link next to "History".
Before getting started, make sure you have [Git LFS installed](../../topics/git/lfs/index.md) in your computer. Open a terminal window and run:
After you lock a file or directory, it will appear as locked in the repository
view.
```shell
git-lfs --version
```
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:
![Repository view](img/file_lock_repository_view.png)
```shell
brew install git-lfs
```
Once locked, any merge request to the default branch will fail
to merge until the file becomes unlocked.
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:
## Unlocking a file or a directory
```shell
git lfs install
```
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".
Check this document to learn more about [using Git LFS](../../topics/git/lfs/index.md#using-git-lfs).
You can unlock a file that yourself or someone else previously locked as long
as you have Maintainer or above [permissions](../permissions.md) to the project.
### Configure Exclusive File Locks
## Viewing and managing existing locks
You need [Maintainer permissions](../permissions.md) to configure
Exclusive File Locks for your project through the command line.
To view or manage every existing lock, navigate to the
**Project > Repository > Locked Files** area. There, you can view all existing
locks and [remove the ones you have permission for](#permissions-on-file-locking).
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
in LFS and flag them as lockable:
## Permissions on file locking
```shell
git lfs track "*.png" --lockable
```
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.
After executing the above command a file named `.gitattributes` will be
created or updated with the following content:
Locks can be created by any person who has [push access](../permissions.md) to the repository; i.e.,
Developer and higher level, and can be removed solely by their author and any
user with Maintainer permissions and above.
```shell
*.png filter=lfs diff=lfs merge=lfs -text lockable
```
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:
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
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 Administrator
To https://example.com/gitlab-org/gitlab-foss.git
! [remote rejected] master -> master (pre-receive hook declined)
error: failed to push some refs to 'https://example.com/gitlab-org/gitlab-foss.git'
*.pdf lockable
```
Similarly, when a user that is not the author of the locked state of a file
accepts a merge request, an error message will appear stating that the file
is locked.
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**.
### Lock files
To lock a file with Exclusive File Locking, open a terminal window in your
repo and:
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 path/to/file.png
```
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
```
You can also unlock by file ID:
```shell
git lfs unlock --id=123
```
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 --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
To list all the files locked with LFS locally, open a terminal window in your
repo and run:
```shell
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 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`).
Changes to locked files on the default branch will be blocked, including merge
requests that modify locked files. Unlock the file to allow changes.
### Lock a file or a directory
To lock a file:
1. Open the file or directory in GitLab.
1. Click the **Lock** button, located near the Web IDE button.
![Locking file](img/file_lock.png)
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.
### 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.
![Merge request error message](img/file_lock_merge_request_error_message.png)
This list shows all the files locked either through LFS or GitLab UI.
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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7