From e55e009fec00935f4c63d46d40b4c01b9821cb96 Mon Sep 17 00:00:00 2001 From: pared Date: Mon, 22 Apr 2019 12:49:41 -0700 Subject: [PATCH 1/2] dvcignore: initial description --- static/docs/user-guide/dvcignore.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 static/docs/user-guide/dvcignore.md diff --git a/static/docs/user-guide/dvcignore.md b/static/docs/user-guide/dvcignore.md new file mode 100644 index 0000000000..26faffca23 --- /dev/null +++ b/static/docs/user-guide/dvcignore.md @@ -0,0 +1,26 @@ +# .dvcignore files + +Sometimes you might want DVC to ignore files while traversing the project +directory. For example, when working on project with many files in its data +directory, you might encounter extended execution time for operations +that are as simple as `dvc status`. To prevent this, we are implementing +`.dvcignore` files handling. When fully implemented, their implementation is +intended to provide similar funcionality as `.gitignore` files provide for +`git`. + +## Syntax + +The same as for [`.gitignore`](https://git-scm.com/docs/gitignore). + +## Current limitations + +During development, we noticed that there are few potential uses cases that +might be tricky to handle (e.g. what to do when we are `dvc add`-ing +directory containing `.dvcignore` file). Therefore, we decided to enable +this feature gradually in different parts of the project. + +Currently .dvcignore files will be read and applied in any operation that +collects stage files(e.g. `checkout`, `metrics`, `status`, `run`, +`repro`), so it is advised to use it in case described in first paragraph, +when amount of files in tree of repository directory causes performance issues. + From 4ea2ccacb8fa843e3112858d17166d34957ec823 Mon Sep 17 00:00:00 2001 From: pared Date: Fri, 26 Apr 2019 18:00:17 -0700 Subject: [PATCH 2/2] dvcignore: add to sidebar, more description how does it work, example --- src/Documentation/sidebar.json | 3 +- static/docs/user-guide/dvcignore.md | 90 ++++++++++++++++++++++++----- 2 files changed, 77 insertions(+), 16 deletions(-) diff --git a/src/Documentation/sidebar.json b/src/Documentation/sidebar.json index 640d3bdbdb..184a8f476b 100644 --- a/src/Documentation/sidebar.json +++ b/src/Documentation/sidebar.json @@ -58,7 +58,8 @@ "update-tracked-file.md", "autocomplete.md", "plugins.md", - "analytics.md" + "analytics.md", + "dvcignore.md" ], "labels": { "dvc-files-and-directories.md": "Files and Directories", diff --git a/static/docs/user-guide/dvcignore.md b/static/docs/user-guide/dvcignore.md index 26faffca23..1b422c85ce 100644 --- a/static/docs/user-guide/dvcignore.md +++ b/static/docs/user-guide/dvcignore.md @@ -1,26 +1,86 @@ -# .dvcignore files +# dvcignore -Sometimes you might want DVC to ignore files while traversing the project -directory. For example, when working on project with many files in its data -directory, you might encounter extended execution time for operations +Mark which files and/or direcotries should be ignored when traversing +repository. + +Sometimes you might want DVC to ignore files while traversing the project +directory. For example, when working on project with many files in its data +directory, you might encounter extended execution time for operations that are as simple as `dvc status`. To prevent this, we are implementing -`.dvcignore` files handling. When fully implemented, their implementation is -intended to provide similar funcionality as `.gitignore` files provide for +`.dvcignore` files handling. When fully implemented, their implementation is +intended to provide similar funcionality as `.gitignore` files provide for `git`. -## Syntax +## How does it work -The same as for [`.gitignore`](https://git-scm.com/docs/gitignore). +* You need to create `.dvcignore` file. +* Populate it with patterns that you would like to ignore. +* Each line should contain only one pattern. +* During execution of commands that traverse directories, DVC will ignore +matching paths. +* Not every operation supports `.dvcignore`. To see current limitations, +read following paragraph. ## Current limitations -During development, we noticed that there are few potential uses cases that -might be tricky to handle (e.g. what to do when we are `dvc add`-ing -directory containing `.dvcignore` file). Therefore, we decided to enable -this feature gradually in different parts of the project. +During development, we noticed that there are few potential uses cases that +might be tricky to handle (e.g. what to do when we are `dvc add`-ing +directory containing `.dvcignore` file). Therefore, we decided to enable +this feature gradually in different parts of the project. -Currently .dvcignore files will be read and applied in any operation that -collects stage files(e.g. `checkout`, `metrics`, `status`, `run`, -`repro`), so it is advised to use it in case described in first paragraph, +Currently .dvcignore files will be read and applied in any operation that +collects stage files(e.g. `checkout`, `metrics`, `status`, `run`, +`repro`), so it is advised to use it in case described in first paragraph, when amount of files in tree of repository directory causes performance issues. +## Syntax + +The same as for [`.gitignore`](https://git-scm.com/docs/gitignore). + +## Example + +Lets analyse example project: + +```dvc + $ mkdir dir1 dir2 + $ echo data1 >> dir1/data1 + $ echo data2 >> dir2/data2 + $ dvc add dir1/data1 dir2/data2 + $ tree . + . + ├── dir1 + │   ├── data1 + │   └── data1.dvc + └── dir2 + ├── data2 + └── data2.dvc +``` +Modify data files +```dvc + $ echo mod > dir1/data1 + $ echo mod > dir2/data2 +``` +Check status +```dvc + $ dvc status + dir1/data1.dvc: + changed outs: + modified: dir1/data1 + dir2/data2.dvc: + changed outs: + modified: dir2/data2 +``` +Note, that both data files are displayed as modified +Create `.dvcignore` file and insert pattern matching one of the files: +```dvc + $ echo dir1/* >> .dvcignore +``` +Check status again +```dvc + $ dvc status + dir2/data2.dvc: + changed outs: + modified: dir2/data2 +``` +Only second file is displayed because DVC ignores `data1.dvc` and `data1` +when collecting stage files. \ No newline at end of file