diff --git a/public/static/docs/command-reference/config.md b/public/static/docs/command-reference/config.md index f440ddab9c..84b06d20df 100644 --- a/public/static/docs/command-reference/config.md +++ b/public/static/docs/command-reference/config.md @@ -114,18 +114,9 @@ for more details.) This section contains the following options: > option, properly transforming paths relative to the current working > directory into paths relative to the config file location. -- `cache.protected` - make DVC-tracked files read-only. Possible values are - `true` or `false` (default). Run `dvc checkout` after changing the value of - this option for the change to go into effect. - - Due to the way DVC handles linking between the data files in the cache and - their counterparts in the workspace, it's easy to accidentally - corrupt the cached file by editing or overwriting it. Turning this config - option on forces you to run `dvc unprotect` before updating a file, providing - an additional layer of security to your data. - - We highly recommend enabling `cache.protected` when `cache.type` is set to - `hardlink` or `symlink`. +- `cache.protected` - obsoleted. When using `hardlink` or `symlink` as + `cache.type`, they will automatically be read-only. Use `dvc unprotect` + before updating a file. - `cache.type` - link type that DVC should use to link data files from cache to the workspace. Possible values: `reflink`, `symlink`, `hardlink`, `copy` or a @@ -136,9 +127,10 @@ for more details.) This section contains the following options: to protect user from accidental cache and repository corruption. ⚠️ If you manually set `cache.type` to `hardlink` or `symlink`, **you will - corrupt the cache** if you modify tracked data files in the workspace. See the - `cache.protected` option above, and corresponding `dvc unprotect` command to - modify files safely. + corrupt the cache** if you modify tracked data files in the workspace. In + an attempt to prevent that, DVC will automatically make those links + read-only and an additional barrier. Use `dvc unprotect` command to modify + files safely. There are pros and cons to different link types. Refer to [File link types](/doc/user-guide/large-dataset-optimization#file-link-types-for-the-dvc-cache) @@ -276,9 +268,3 @@ Set cache type: if `reflink` is not available, use `copy`: ```dvc $ dvc config cache.type reflink,copy ``` - -Protect DVC-tracked data files by making them read-only: - -```dvc -$ dvc config cache.protected true -``` diff --git a/public/static/docs/command-reference/unprotect.md b/public/static/docs/command-reference/unprotect.md index e59c94355a..6149fb488d 100644 --- a/public/static/docs/command-reference/unprotect.md +++ b/public/static/docs/command-reference/unprotect.md @@ -1,7 +1,7 @@ # unprotect -Unprotect tracked files or directories (when the cache protected -mode has been enabled with `dvc config cache`). +Unprotect tracked files or directories (when hardlinks or symlinks have been +enabled with `dvc config cache.type`). ## Synopsis @@ -19,9 +19,9 @@ to link tracked data files from the cache to the workspace. However, these types of file links can be enabled with `dvc config cache` (`cache.type` config option). -Enabling hardlinks or symlinks also requires the `cache.protected` mode to be -turned on, which makes the tracked data files in the workspace read-only. (This -prevent users from accidentally corrupting the cache by modifying file links.) +Enabling hardlinks or symlinks makes the tracked data files in the workspace +read-only. (This prevent users from accidentally corrupting the cache by +modifying file links.) Running `dvc unprotect` guarantees that the target files or directories (`targets`) in the workspace are physically "unlinked" from the cache and can be @@ -30,8 +30,7 @@ safely updated. Read the more on this process. `dvc unprotect` can be an expensive operation (involves copying data). Check -first whether your task matches one of the cases that are considered safe, even -when cache protected mode is enabled: +first whether your task matches one of the cases that are considered safe: - Adding more files to a directory input dataset (say, images or videos) - Deleting files from a directory dataset @@ -47,10 +46,10 @@ when cache protected mode is enabled: ## Examples -Enable cache protected mode is enabled: +Enable symlinks: ```dvc -$ dvc config cache.protected true +$ dvc config cache.type symlink ``` Track a data file with DVC: diff --git a/public/static/docs/user-guide/large-dataset-optimization.md b/public/static/docs/user-guide/large-dataset-optimization.md index 144ffd3aaf..2ce7ab7658 100644 --- a/public/static/docs/user-guide/large-dataset-optimization.md +++ b/public/static/docs/user-guide/large-dataset-optimization.md @@ -40,9 +40,10 @@ platforms yet. Hard/soft links optimize **speed** and **space** in the file system, but may break your workflow since updating hard/sym-linked files tracked by DVC in the workspace causes cache corruption. These 2 link types thus require using cache **protected mode** (see the -`cache.protected` config option in `dvc config cache`). Finally, a 4th "linking" -alternative is to actually copy files from/to the cache, which is safe but -inefficient – especially for large files (several GBs or more). +`cache.protected` config option in `dvc config cache`), which is enabled +by-default and makes your files read-only. Finally, a 4th "linking" alternative +is to actually copy files from/to the cache, which is safe but inefficient – +especially for large files (several GBs or more). > Some versions of Windows (e.g. Windows Server 2012+ and Windows 10 Enterprise) > support hard or soft links on the @@ -110,13 +111,12 @@ configure DVC like this: ```dvc $ dvc config cache.type hardlink,symlink -$ dvc config cache.protected true ``` > Refer to `dvc config cache` for more details. -Setting `cache.protected` is important with `hardlink` and/or `symlink` cache -file link types. Please refer to the +Note that your workspace files will be in read-only mode because of the efforts +to protect cache from corruption. Please refer to the [Update a Tracked File](/doc/user-guide/updating-tracked-files) on how to manage tracked files under these cache configurations.