docs: rewrite copy/add instruction reference #5128
Conversation
dvdksn
force-pushed
the
dockerfile-reference-copy-add
branch
from
2540e8e
to
56d154b
Compare
| > **Note** | ||
| > | ||
| > The first encountered `ADD` instruction will invalidate the cache for all | ||
| > following instructions from the Dockerfile if the source has changed. This |
There was a problem hiding this comment.
Invalidate cache for the following commands in the same stage is what you probably mean. But even that is not true for all cases, eg. COPY --link
Also, this behavior isn't really specific to ADD or COPY command.
There was a problem hiding this comment.
I can remove this, we cover cache invalidation elsewhere.
| @@ -1160,41 +1160,96 @@ The available `[OPTIONS]` are: | |||
| - [`--link`](#add---link) | |||
| - [`--exclude`](#add---exclude) | |||
|
|
|||
| The `ADD` instruction copies new files, directories or remote file URLs from `<src>` | |||
| and adds them to the filesystem of the image at the path `<dest>`. | |||
| The `ADD` instruction copies new files or directories from `<src>` and adds | |||
There was a problem hiding this comment.
It would be nice to have some comparison of ADD/COPY or guidance on when to use which one. I've seen plenty of recommendations that "you should use COPY and not ADD," and while that might be a good idea for consistency, they sometimes imply that COPY is faster or smth. what is not true.
There was a problem hiding this comment.
We do have a section on this in the best practices document. https://docs.docker.com/build/building/best-practices/#add-or-copy
I can add a reference to that doc from these sections.
There was a problem hiding this comment.
We can of course expand on that section too - let me know if you have some suggestions
| If the source is a directory, the contents of the directory are copied, | ||
| including filesystem metadata. The directory itself isn't copied, only its | ||
| contents. If it contains subdirectories, these are also copied, and merged with | ||
| any existing directories at the destination. Any conflicts are resolved in |
There was a problem hiding this comment.
Any conflicts are resolved in
Not worth complicating probably, but this is true if files are of the same type. If you have a directory and replace it with a regular file, you get an error.
There was a problem hiding this comment.
I can add this, just to avoid any confusion.
| #### Adding local tar archives | ||
|
|
||
| When using a local tar archive as the source for `ADD`, and the archive is in a | ||
| recognized compression format (`identity`, `gzip`, `bzip2` or `xz`), the |
There was a problem hiding this comment.
identity ?
Do you mean gzip, bzip2, xz or uncompressed?
There was a problem hiding this comment.
Probably! I didn't touch this sentence but sounds better to me, I'll update
Signed-off-by: David Karlsson <[email protected]>
dvdksn
force-pushed
the
dockerfile-reference-copy-add
branch
from
56d154b
to
60c86c4
Compare
Updates the sections for COPY and ADD in the Dockerfile reference to make it
easier to understand the behaviors of these instructions in different
circumstances.
Also adds some information about permissions for COPY with Git contexts.
Preview:
Relates to: