Enhancement: Add descriptive name for docker container images

[Takshil-Kunadia]

Resolves #64153

What?

The docker container image names are indistinguishable. See screenshots shared in #64153

Container, image, and cache-directory names generated by wp-env are an indistinguishable wall of md5 hashes. This PR replaces them with readable, directory-aware names while preserving every existing environment on disk.

Why?

It would enhance the clarity and usability of directory names generated by wp-env. Using more descriptive names based on the project folder and file would make it easier to identify directories. Container names remain unique while reducing clutter in file explorers or Docker, making management more efficient. This solution would simplify troubleshooting and improve workflow for developers.

How?

Instead of directly using MD5 of the directory name

gutenberg/packages/env/lib/config/load-config.js

Lines 45 to 48 in f9b966b

	const cacheDirectoryPath = path.resolve(
	await getCacheDirectory(),
	md5( configFilePath )
	);

As suggested use a prefix. Prepend it with wp-env-<project-dir>[-<variant>]-<short-hash>

Backwards compatibility

Upgrading wp-env must not orphan a running environment. If the legacy pure-md5 cache directory already exists for a given config file, wp-env keeps using it; the new descriptive name only takes effect for fresh environments.

Adopting the new names on an existing environment

Run wp-env destroy followed by wp-env start. (destroy will delete all resources, please test this in a new env, not an old one whose data you wanna preserve)

Testing Instructions

1. Check out this branch, npm run build.
2. From any project folder with a .wp-env.json, run npm run wp-env start.
3. Confirm ls ~/.wp-env/ shows wp-env-<folder>-<8hex>/.
4. Confirm docker ps shows readable container names.
5. Parallel-env test: in the same folder, run npx wp-env start --config .wp-env.test.json, container names should include -test-.
6. Parent/child test: .wp-env.json in a subdirectory of another project with .wp-env.json should produce a distinct cache dir.

Screenshots

Before	After

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: Takshil-Kunadia <takshil@git.wordpress.org>
Co-authored-by: mcsf <mcsf@git.wordpress.org>
Co-authored-by: BrianHenryIE <brianhenryie@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[BrianHenryIE]

Hey, thanks for implementing this. The one change I would suggest would be to check is there already a cache directory for this project. Otherwise people will npm update, npx wp-env start and they will "lose" any work they have done on their existing container.

Option 1: keep using the old directory

// Traditional cache directory name
const md5CacheDirectoryPath = path.resolve(
	await getCacheDirectory(),
	md5( configFilePath )
);
// If there is an older-style cache directory, use that, otherwise use the more descriptive name.
const cacheDirectoryPath = fs.existsSync( md5CacheDirectoryPath )
	? md5CacheDirectoryPath
	: path.resolve(
	await getCacheDirectory(),
	'wp-env-' + directory + '-' + md5( configFilePath )
);

Option 2: Rename the old directory to the new name

// Traditional cache directory name
const md5CacheDirectoryPath = path.resolve(
	await getCacheDirectory(),
	md5( configFilePath )
);
// Newer, more descriptive directory name
const cacheDirectoryPath = path.resolve(
	await getCacheDirectory(),
	'wp-env-' + directory + '-' + md5( configFilePath )
);
// If there is an older-style cache directory, rename it to the more descriptive name.
if(fs.existsSync( md5CacheDirectoryPath )) {
	await fs.promises.rename( md5CacheDirectoryPath, cacheDirectoryPath );
}

The first option is safe.

The second one is probably safe – I don't know where else this id might be used. I guess in Docker itself, once the directory is renamed Docker will treat it as missing. If the container is already running when npx wp-env start is run, then the rename operation might fail.

NB: I don't write much JavaScript and I haven't tested that code.

[Takshil-Kunadia]

@BrianHenryIE Thanks for looking into this! As per your guidance, I am in favour of Option 1 as it is relatively much safer. I've ensured that if an older cache directory exists than it uses that, else create with the more descriptive name.

[BrianHenryIE]

Can we get this merged? @t-hamano @mcsf

[Takshil-Kunadia]

Updated the PR @BrianHenryIE
Ready for merge ✅ @t-hamano @mcsf

[mcsf]

I've left a few suggestions, but I'm interested in more opinions.

[Takshil-Kunadia]

Updates since last review:-

• Directory names use 8-char short hash, 5fea4c5689ef6cc4a4e6eaaa39323338 to 5fea4c56.
• Variant is extracted from the config file name .wp-env.test.json leads to -test- segment in the name. So the parallel-env case you flagged now produces:

wp-env-gutenberg-4f82b1c3-wordpress-1        # dev
wp-env-gutenberg-test-05be9432-wordpress-1   # test env

[Takshil-Kunadia]

Hi @mcsf hoping to get your review, whenever you get some bandwidth 🙂

[mcsf]

Thanks for your work and for your patience, @Takshil-Kunadia!

[mcsf]

It's a minor point by now, but we should avoid computing this path when we don't need it:

const cacheDirPath = existsSync( legacyPath )
  ? legacyPath
  : path.resolve(
      await getCacheDir(),
      buildDescriptiveName( conf ))

or, more readable:

let cacheDirPath = legacyPath
if ( ! exists( cacheDirPath ) ) {
  cacheDirPath = path.resolve(
    ..
  )
}

[mcsf]

I didn't want to block your PR because of this small thing, so feel free to submit a subsequent patch for this!

[Takshil-Kunadia]

I raise a follow up PR to implement this lazy-evaluation 👍