Gotcha: Docker COPY and ADD behave differently with directories

COPY and ADD in Dockerfiles have subtle differences that cause unexpected behavior with archives, URLs, and directory structures.

Key differences and gotchas:

# COPY - straightforward file copy:
COPY src/ /app/src/ # Copies CONTENTS of src/ into /app/src/
COPY src /app/src # Same as above
COPY file.txt /app/ # Copies file into /app/file.txt
COPY file.txt /app/new.txt # Copies and renames

# ADD - has extra features (use COPY instead unless you need them):
ADD archive.tar.gz /app/ # Auto-extracts! COPY doesn't
ADD https://example.com/f /app/ # Downloads URL! (don't use, prefer curl)

# Directory gotcha:
COPY src/ /app/ # Copies CONTENTS of src/ (not the src dir itself)
# If src/ contains main.py, you get /app/main.py
# NOT /app/src/main.py

# To preserve directory name:
COPY src/ /app/src/ # Explicit destination includes dir name

# Trailing slash matters:
COPY file.txt /app # If /app doesn't exist, creates FILE named 'app'
COPY file.txt /app/ # Creates /app/ directory, puts file inside

# Best practice: Always use COPY, use ADD only for tar extraction