Summary

When I use ansible.builtin.copy with a directory source and --check --diff, and there are changed files, I expect the differences to be shown. However, only "changed": true is reported with not additional info.

I struggled to decide on an issue type for this one, becuase it comes down to authorial intent.
The copy module's docs claim it has full support for diff mode.

• If it's meant to have diff mode for recursive copying, but doesn't, that's a bug.
• If it was never meant to have diff mode for recursive copying, and shouldn't, then there's a documentation issue.
• If it was never meant to have diff mode for recursive copying, but should, then I guess this is a feature request?

I'm happy to take a swing at implementing this. If you think this will have bad performance, then perhaps it could be enabled with a module argument. (Yes, it feels weird to have an argument that only applies to diff mode, but what else would we do? I guess a config var?)

Issue Type

Bug Report

Component Name

ansible.builtin.copy

Ansible Version

$ ansible --version
ansible [core 2.20.4]
  config file = /Users/kevin/.ansible.cfg
  configured module search path = ['/Users/kevin/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /Users/kevin/code/private-infra/.venv/lib/python3.14/site-packages/ansible
  ansible collection location = /Users/kevin/.ansible/collections:/usr/share/ansible/collections
  executable location = /Users/kevin/code/private-infra/.venv/bin/ansible
  python version = 3.14.3 (main, Feb  3 2026, 15:32:20) [Clang 17.0.0 (clang-1700.6.3.2)] (/Users/kevin/code/private-infra/.venv/bin/python3)
  jinja version = 3.1.6
  pyyaml version = 6.0.3 (with libyaml v0.2.5)

Configuration

# if using a version older than ansible-core 2.12 you should omit the '-t all'
$ ansible-config dump --only-changed -t all
CONFIG_FILE() = /Users/kevin/.ansible.cfg
EDITOR(env: EDITOR) = nvim

GALAXY_SERVERS:

OS / Environment

Python 3.14.3 on macOS 15.7.5

Steps to Reproduce

set -euo pipefail

workspace=$(mktemp -d)
echo "remove tempdir $workspace yourself afterwards if you're done"

cd "$workspace"

mkdir src dest; echo foo > src/file1; echo bar > src/file2

function run-copy {
    ansible -i localhost, -c local \
        -m ansible.builtin.copy -a "src=src/ dest=dest" \
        "$@" localhost
}

echo "copying files, should say changed"
run-copy

echo "checking copy, should _not_ say changed"
run-copy --check --diff

echo "not foo" > src/file1
echo "checking after changed"
run-copy --check --diff

Expected Results

It should have shown diffs between the changed files.

Actual Results

localhost | CHANGED => {
    "changed": true,
    "dest": "dest/",
    "src": "/private/var/folders/bt/bg6m02_92zq_2fjpg255ccpm0000gn/T/tmp.iSSsxfcQFd/src/"
}

Code of Conduct

• I agree to follow the Ansible Code of Conduct