v3.0.0

[lucatume]

This PR replaces the #225 one and builds on the multi-stacks support to implement worktree support.
If I read it correctly, this should also replace #220.

Multi-stack demo
Worktree support demo
Interactive use selection demo
shell completions demo - demo on zsh as that is the one I use

The two main feature in detail:

Multi-stack support

Assume there two plugin directories I'm working on:

• /Users/lucatume/project-1/plugins, this has the plugin plugin-1 that has the wpunit suite
• /Users/lucatuem/project-2/plugins, this has the plugin plugin-2 that has the integration suite

If I want to run the wpunit suite on plugin-1 in the first path, and the integration suite on plugin-2 in the second path, these are the before and after flows:

Before

cd /Users/lucatume/project-1/plugins
slic here
slic use plugin-1
slic run wpunit

Then wait for the tests to complete ...

cd /Users/lucatume/project-2/plugins
slic here
slic use plugin-2
slic run integration

Then wait for the tests to complete.

The context change introduced by the single slic stack is this:

cd <project_plugins_path>
slic here
slic use <project_target>

And it has to be done over and over for each context change, killing the possible benefit of working on other projects while long-runing operations (like tests) complete.

After

Same requirements, but:

cd /Users/lucatume/project-1/plugins
slic here
slic use plugin-1
slic run wpunit

Nothing changed in the commands I'm running, but now I do not need to wait for the tests to be done to run tests on another project.
In a new terminal tab/window:

cd /Users/lucatume/project-2/plugins
slic here
slic use plugin-2
slic run integration

I can keep running tests (and using slic shells and all other commands) without having to change context.

Deterministic stack names and XDebug ports

By default, docker would assign random names to the stacks created and would allocate random ports.
To avoid having to reconfigure the IDE on each slic down && slic up cycle, the multi-stack feature build the project name and XDebug remote port deterministically from the path of the stack.

I.e. the stack for /Users/Alice/acme/wp-content/plugins will have the same project name (slic_... that is also the XDebug server_name) and Xdebug remote port.
The xdebug commands have been updated to take that into account and provide the correct information depending on the stack.

Worktree support

Building on this multi-stack support, understanding the worktree support is easier.

For "worktree" here I mean the "git worktree" support; I will not delve into what git worktree does, but in very short terms it allows copying the repository to a linked directory; it replaces changing branch with changing directory.

Git branch vs worktree flow

This is required to understand how slic wraps the worktree functionality. To "ground" the example I will use the-events-calendar plugin located at /Users/lucatume/tec-dev/wp-content/plugins/the-events-calendar.

In this example I'm working on two issues: fix/issue-1 and fix/issue-2.

*With branches

cd /Users/lucatume/tec-dev/wp-content/plugins
slic here
slic use the-events-calendar
cd the-events-calendar
git checkout main
git checkout --branch fix/issue-1

Work on fix/issue-1, run some test using slic:

slic run wpunit

And when done change to fix/issue-2:

git checkout main
git checkout --branch fix/issue-2

Again work in fix/issue-2, run some tests and wrap the fix.

This is fine, but the use of worktrees could get rid of some lull times.

With git worktree

cd /Users/lucatume/tec-dev/wp-content/plugins
slic here
slic use the-events-calendar
cd the-events-calendar
git checkout main
git worktree add ../the-events-calendar-fix-issue-1 -b fix/issue-1
git worktree add ../the-events-calendar-fix-issue-2 -b fix/issue-2

This is the new directory structure:

/Users/lucatume/tec-dev/wp-content/plugins
  - the-events-calendar                    <- current slic target
  - the-events-calendar-fix-issue-1
  - the-events-calendar-fix-issue-2

To work on fix/issue-1 I would need to change target:

slic use the-events-calendar-fix-issue-1

BUT all the test files are set to use the-events-calendar directory (without the -fix-issue-1 postfix) and, in short, what I will be testing will always be the-events-calendar.

One thing to note is the volume binding done in the slic and wordpress services in the stack:

GUEST /Users/lucatume/tec-dev/wp-content/plugins -> HOST /var/www/html/wp-content/plugins

This means the directory structure will be reflected in the container:

/var/www/html/wp-content/plugins
  - the-events-calendar                    <- current slic target
  - the-events-calendar-fix-issue-1
  - the-events-calendar-fix-issue-2

So, worktree support is not really workable out of the box.

Slic worktree support

Slic wraps in very limited capacity some git worktree commands, notably for this example, the commnands will change to:

cd /Users/lucatume/tec-dev/wp-content/plugins
slic here
slic use the-events-calendar
cd the-events-calendar
git checkout main
slic worktree add fix/issue-1
slic worktree add fix/issue-2

The same directory structures have been created, but slic created a dedicated stack for each worktree under the hood.

This means this flow is now possible:

# Change to the the worktree fix/issue-1 directory.
cd /users/lucatume/tec-dev/wp-content/plugins/the-events-calendar-fix-issue-1

# Using the path slic knows what stack to use: the fix/issue-1 worktree one
slic run wpunit

cd /users/lucatume/tec-dev/wp-content/plugins/the-events-calendar-fix-issue-2
slic run integration

Notably, slic uses the "shadowing" provided by volume binding override to have these volume binds in the fix/issue-1 worktree:

GUEST /Users/lucatume/tec-dev/wp-content/plugins -> HOST /var/www/html/wp-content/plugins
GUEST /Users/lucatume/tec-dev/wp-content/plugins/the-events-calendar-fix-issue-1 -> HOST /var/www/html/wp-content/plugins/the-events-calendar
GUEST /Users/lucatume/tec-dev/wp-content/plugins/the-events-calendar-fix-issue-2 -> HOST /var/www/html/wp-content/plugins/the-events-calendar-fix-issue-2 (implicit from the plugins binding)

And these volume binds in the fix/issue-2 worktree:

GUEST /Users/lucatume/tec-dev/wp-content/plugins -> HOST /var/www/html/wp-content/plugins
GUEST /Users/lucatume/tec-dev/wp-content/plugins/the-events-calendar-fix-issue-1 -> HOST /var/www/html/wp-content/plugins/the-events-calendar-fix-issue-1 (implicit from the plugins binding)
GUEST /Users/lucatume/tec-dev/wp-content/plugins/the-events-calendar-fix-issue-2 -> HOST /var/www/html/wp-content/plugins/the-events-calendar

So the use target (the-events-calendar in this example) is actually from the worktree directory.

Wait! In the second example the fix/issue-1 worktree directory will still be bound in the container!

Yes, the same would be true for any other worktree. The idea is that having them there will not cause issues. WordPress uses the plugin directory name to identify the plugins, so they will be just like any other unused plugin directory.

The PR contains many more commands and changes, but all of them geared toward supporting this new features.

Tests

This PR contains the setup and scaffolding of PHPUnit tests as well. The complete body of tests is in #238.