Merge branch 'jousch/gitlab-ce-ci-untracked-doku-docs' into 'master'

Add dedicated info about artifacts:untracked to GitLab CI's README.md

See merge request gitlab-org/gitlab-ce!18342

1 files changed, 49 insertions, 30 deletions

diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index 68aa64b3834..bd7ffb2befb 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -869,37 +869,29 @@ skip the download step.
 - Introduced in GitLab Runner v0.7.0 for non-Windows platforms.
 - Windows support was added in GitLab Runner v.1.0.0.
 - From GitLab 9.2, caches are restored before artifacts.
-- Currently not all executors are supported.
+- Not all executors are [supported](https://docs.gitlab.com/runner/executors/#compatibility-chart).
 - Job artifacts are only collected for successful jobs by default.
 
 `artifacts` is used to specify a list of files and directories which should be
-attached to the job after success. You can only use paths that are within the
-project workspace. To pass artifacts between different jobs, see [dependencies](#dependencies).
-Below are some examples.
+attached to the job after success.
 
-Send all files in `binaries` and `.config`:
+The artifacts will be sent to GitLab after the job finishes successfully and will
+be available for download in the GitLab UI.
 
-```yaml
-artifacts:
-  paths:
-  - binaries/
-  - .config
-```
+[Read more about artifacts.](../../user/project/pipelines/job_artifacts.md)
 
-Send all Git untracked files:
+### `artifacts:paths`
 
-```yaml
-artifacts:
-  untracked: true
-```
+You can only use paths that are within the project workspace. To pass artifacts
+between different jobs, see [dependencies](#dependencies).
 
-Send all Git untracked files and files in `binaries`:
+Send all files in `binaries` and `.config`:
 
 ```yaml
 artifacts:
-  untracked: true
   paths:
   - binaries/
+  - .config
 ```
 
 To disable artifact passing, define the job with empty [dependencies](#dependencies):
@@ -933,11 +925,6 @@ release-job:
     - tags
 ```
 
-The artifacts will be sent to GitLab after the job finishes successfully and will
-be available for download in the GitLab UI.
-
-[Read more about artifacts.](../../user/project/pipelines/job_artifacts.md)
-
 ### `artifacts:name`
 
 > Introduced in GitLab 8.6 and GitLab Runner v1.1.0.
@@ -954,26 +941,30 @@ To create an archive with a name of the current job:
 job:
   artifacts:
     name: "$CI_JOB_NAME"
+    paths:
+    - binaries/
 ```
 
 To create an archive with a name of the current branch or tag including only
-the files that are untracked by Git:
+the binaries directory:
 
 ```yaml
 job:
    artifacts:
      name: "$CI_COMMIT_REF_NAME"
-     untracked: true
+    paths:
+    - binaries/
 ```
 
 To create an archive with a name of the current job and the current branch or
-tag including only the files that are untracked by Git:
+tag including only the binaries directory:
 
 ```yaml
 job:
   artifacts:
     name: "$CI_JOB_NAME-$CI_COMMIT_REF_NAME"
-    untracked: true
+    paths:
+    - binaries/
 ```
 
 To create an archive with a name of the current [stage](#stages) and branch name:
@@ -982,7 +973,8 @@ To create an archive with a name of the current [stage](#stages) and branch name
 job:
   artifacts:
     name: "$CI_JOB_STAGE-$CI_COMMIT_REF_NAME"
-    untracked: true
+    paths:
+    - binaries/
 ```
 
 ---
@@ -994,7 +986,8 @@ If you use **Windows Batch** to run your shell scripts you need to replace
 job:
   artifacts:
     name: "%CI_JOB_STAGE%-%CI_COMMIT_REF_NAME%"
-    untracked: true
+    paths:
+    - binaries/
 ```
 
 If you use **Windows PowerShell** to run your shell scripts you need to replace
@@ -1004,7 +997,33 @@ If you use **Windows PowerShell** to run your shell scripts you need to replace
 job:
   artifacts:
     name: "$env:CI_JOB_STAGE-$env:CI_COMMIT_REF_NAME"
-    untracked: true
+    paths:
+    - binaries/
+```
+
+### `artifacts:untracked`
+
+`artifacts:untracked` is used to add all Git untracked files as artifacts (along
+to the paths defined in `artifacts:paths`).
+
+NOTE: **Note:**
+To exclude the folders/files which should not be a part of `untracked` just
+add them to `.gitignore`.
+
+Send all Git untracked files:
+
+```yaml
+artifacts:
+  untracked: true
+```
+
+Send all Git untracked files and files in `binaries`:
+
+```yaml
+artifacts:
+  untracked: true
+  paths:
+  - binaries/
 ```
 
 ### `artifacts:when`