The uid mismatch that makes bind mounts unusable on Linux

On macOS the file sharing layer papers over ownership. On Linux it does not: a container writing as uid 1000 into a bind mount owned by uid 1001 gets permission denied, and every developer has a different uid.

# docker-compose.override.yml — local only
services:
  php:
    build:
      args:
        UID: ${UID:-1000}
        GID: ${GID:-1000}

# and in the Dockerfile
# ARG UID=1000
# ARG GID=1000
# RUN usermod -u $UID app && groupmod -g $GID app

# .env, generated once per machine:
#   UID=$(id -u)
#   GID=$(id -g)

This is an hour of everyone’s life, once per team, and it never appears on macOS so it is easy to ship a stack that only works for half the people. The alternative some teams take — running the container as root and living with root-owned files appearing in the repository — trades a build-time problem for a permanent one. Generating the two variables in a setup script means nobody has to know why they exist.