From f5ad05765d06c24b83a8191410de146fcc4e7959 Mon Sep 17 00:00:00 2001
From: Talon Bowler <talon.bowler@docker.com>
Date: Tue, 9 Jul 2024 09:18:28 -0700
Subject: [PATCH] Add CopyIgnoredFile documentation

Signed-off-by: Talon Bowler <talon.bowler@docker.com>
---
 frontend/dockerfile/docs/rules/_index.md      |  4 ++
 .../docs/rules/copy-ignored-file.md           | 45 +++++++++++++++++++
 .../dockerfile/linter/docs/CopyIgnoredFile.md | 37 +++++++++++++++
 frontend/dockerfile/linter/ruleset.go         |  2 +-
 4 files changed, 87 insertions(+), 1 deletion(-)
 create mode 100644 frontend/dockerfile/docs/rules/copy-ignored-file.md
 create mode 100644 frontend/dockerfile/linter/docs/CopyIgnoredFile.md

diff --git a/frontend/dockerfile/docs/rules/_index.md b/frontend/dockerfile/docs/rules/_index.md
index 0980d5d398ec3..8639747c997a5 100644
--- a/frontend/dockerfile/docs/rules/_index.md
+++ b/frontend/dockerfile/docs/rules/_index.md
@@ -92,5 +92,9 @@ $ docker build --check .
       <td><a href="./invalid-default-arg-in-from/">InvalidDefaultArgInFrom</a></td>
       <td>Default value for global ARG results in an empty or invalid base image name</td>
     </tr>
+    <tr>
+      <td><a href="./copy-ignored-file/">CopyIgnoredFile</a></td>
+      <td>Attempting to Copy file that is excluded by .dockerignore</td>
+    </tr>
   </tbody>
 </table>
diff --git a/frontend/dockerfile/docs/rules/copy-ignored-file.md b/frontend/dockerfile/docs/rules/copy-ignored-file.md
new file mode 100644
index 0000000000000..7a7113635853d
--- /dev/null
+++ b/frontend/dockerfile/docs/rules/copy-ignored-file.md
@@ -0,0 +1,45 @@
+---
+title: CopyIgnoredFile
+description: Attempting to Copy file that is excluded by .dockerignore
+aliases:
+  - /go/dockerfile/rule/copy-ignored-file/
+---
+
+## Output
+
+```text
+Attempting to Copy file "./tmp/Dockerfile" that is excluded by .dockerignore
+```
+
+## Description
+
+When you use the Add or Copy instructions from within a Dockerfile, you should
+ensure that the files to be copied into the image do not match a pattern
+present in `.dockerignore`.
+
+Files which match the patterns in a `.dockerignore` file are not present in the
+context of the image when it is built. Trying to copy or add a file which is
+missing from the context will result in a build error.
+
+## Examples
+
+With the given `.dockerignore` file:
+
+```text
+*/tmp/*
+```
+
+❌ Bad: Attempting to Copy file "./tmp/Dockerfile" that is excluded by .dockerignore
+
+```dockerfile
+FROM scratch
+COPY ./tmp/helloworld.txt /helloworld.txt
+```
+
+✅ Good: Copying a file which is not excluded by .dockerignore
+
+```dockerfile
+FROM scratch
+COPY ./forever/helloworld.txt /helloworld.txt
+```
+
diff --git a/frontend/dockerfile/linter/docs/CopyIgnoredFile.md b/frontend/dockerfile/linter/docs/CopyIgnoredFile.md
new file mode 100644
index 0000000000000..1a20ee6eebfe3
--- /dev/null
+++ b/frontend/dockerfile/linter/docs/CopyIgnoredFile.md
@@ -0,0 +1,37 @@
+## Output
+
+```text
+Attempting to Copy file "./tmp/Dockerfile" that is excluded by .dockerignore
+```
+
+## Description
+
+When you use the Add or Copy instructions from within a Dockerfile, you should
+ensure that the files to be copied into the image do not match a pattern
+present in `.dockerignore`.
+
+Files which match the patterns in a `.dockerignore` file are not present in the
+context of the image when it is built. Trying to copy or add a file which is
+missing from the context will result in a build error.
+
+## Examples
+
+With the given `.dockerignore` file:
+
+```text
+*/tmp/*
+```
+
+❌ Bad: Attempting to Copy file "./tmp/Dockerfile" that is excluded by .dockerignore
+
+```dockerfile
+FROM scratch
+COPY ./tmp/helloworld.txt /helloworld.txt
+```
+
+✅ Good: Copying a file which is not excluded by .dockerignore
+
+```dockerfile
+FROM scratch
+COPY ./forever/helloworld.txt /helloworld.txt
+```
diff --git a/frontend/dockerfile/linter/ruleset.go b/frontend/dockerfile/linter/ruleset.go
index f1acb454c5ed3..32e25d8f5dc71 100644
--- a/frontend/dockerfile/linter/ruleset.go
+++ b/frontend/dockerfile/linter/ruleset.go
@@ -151,7 +151,7 @@ var (
 	RuleCopyIgnoredFile = LinterRule[func(string, string) string]{
 		Name:        "CopyIgnoredFile",
 		Description: "Attempting to Copy file that is excluded by .dockerignore",
-		URL:         "",
+		URL:         "https://docs.docker.com/go/dockerfile/rule/copy-ignored-file/",
 		Format: func(cmd, file string) string {
 			return fmt.Sprintf("Attempting to %s file %q that is excluded by .dockerignore", cmd, file)
 		},