# phpstorm-ebuild-svn-commit-helper

PHP CLI helper for Sebastian's SVN-first Gentoo workflow.

Default workflow: PhpStorm commits the source SVN working copy, then this helper reads the resulting source revision, updates the mapped ebuild package directory, copies the newest matching ebuild with source version less than or equal to the current Meson source version with `svn cp` to `<package>-<source-version>_p<source-rev>.ebuild`, regenerates `Manifest`, and commits the new ebuild together with `Manifest`.

The helper never commits source code itself. Commit the source working copy in PhpStorm first, then run this tool via shortcut.

The source-to-ebuild mapping is learned interactively. If a source path has not been used before, the helper asks for the ebuild package directory and stores the mapping under:

```text
~/.config/phpstorm-ebuild-svn-commit-helper/mappings.json
```

## PhpStorm External Tool

After installing the package, read this file under:

```text
/usr/share/doc/phpstorm-ebuild-svn-commit-helper/README.md
```

Create the PhpStorm tool here:

```text
Settings -> Tools -> External Tools -> +
```

Use these values:

```text
Name: Auto Ebuild SVN Commit
Group: SVN / Gentoo
Program: phpstorm-ebuild-svn-commit-helper
Arguments: --source=$FilePath$
Working directory: $FileDir$
```

Use `$FilePath$`, not `$ProjectFileDir$`. In the Project View popup menu `$FilePath$` is the currently selected file or directory; `$ProjectFileDir$` is only the PhpStorm project root and would often be too broad, for example `/home/peters/SVN`.

The source version is read automatically from the source `meson.build` project declaration, for example `version: '0.04'`. If PhpStorm passes a source file or subdirectory as source path, the helper walks upward until it finds the nearest `meson.build`.

If no `meson.build` is found for the selected source path, the helper shows a graphical Zenity error and stops before asking for any source-to-ebuild mapping.

Recommended options:

```text
Synchronize files after execution: enabled
Open console for tool output: enabled
Make console active on message in stdout/stderr: enabled
```

Then run it from:

```text
Tools -> External Tools -> SVN / Gentoo -> Auto Ebuild SVN Commit
```

Optional shortcut:

```text
Settings -> Keymap -> External Tools -> SVN / Gentoo -> Auto Ebuild SVN Commit
```

Optional project-view context menu entry:

```text
Settings -> Appearance & Behavior -> Menus and Toolbars -> Project View Popup Menu
```

Add the external tool action there:

```text
External Tools -> SVN / Gentoo -> Auto Ebuild SVN Commit
```

This makes the helper available from the project tree context menu after the normal PhpStorm SVN commit. A keyboard shortcut can still be assigned separately under Keymap.

This setup is intended for the workflow where PhpStorm performs the normal SVN source commit first, then you press the External Tool shortcut. The helper reads the maximum last-changed SVN revision below the source tree and creates/commits the matching ebuild.

Before selecting the template ebuild, the helper runs `svn update` on the mapped or selected ebuild package directory. In `--dry-run` mode it only prints the update command.

After copying the ebuild, the helper runs:

```bash
DISTDIR=$XDG_CACHE_HOME/phpstorm-ebuild-svn-commit-helper/distfiles-<pid> PORTAGE_RO_DISTDIRS=/var/cache/distfiles ebuild <new-ebuild> manifest
```

The temporary `DISTDIR` avoids write access requirements for `/var/cache/distfiles` and is removed after the manifest step. If `/var/cache/distfiles` is readable, it is passed as `PORTAGE_RO_DISTDIRS` so already existing distfiles can be reused without making that directory writable. The final SVN commit includes both the new ebuild and the updated `Manifest`.

Useful optional arguments:

```text
--source=PATH
--manifest=PACKAGE.ebuild
--ebuild-dir=PATH
--version=VERSION
--yes
--dry-run
```

## Manifest update tool

For updating only the `Manifest` of an existing ebuild, create a second PhpStorm External Tool:

```text
Name: Update Ebuild Manifest
Group: SVN / Gentoo
Program: phpstorm-ebuild-svn-commit-helper
Arguments: --manifest=$FilePath$
Working directory: $FileDir$
```

Use this tool only for `.ebuild` files. The helper validates that `$FilePath$` points to an `.ebuild` file and stops with a graphical Zenity error for anything else.

Recommended PhpStorm setup: add this action only to a context menu or toolbar that you use with ebuild files, or put it into a custom PhpStorm scope/file-color/workflow for `*.ebuild` files if your IDE configuration supports scoped toolbar actions.

The helper runs:

```bash
DISTDIR=$XDG_CACHE_HOME/phpstorm-ebuild-svn-commit-helper/distfiles-<pid> PORTAGE_RO_DISTDIRS=/var/cache/distfiles ebuild <selected-ebuild> manifest
```

If `XDG_CACHE_HOME` is unset, it uses:

```text
~/.cache/phpstorm-ebuild-svn-commit-helper/distfiles-<pid>
```

That distfiles/download directory is created before running `ebuild manifest`, must be writable by the current user, and is removed afterwards. This avoids Portage trying to write to `/var/cache/distfiles` from the PhpStorm-launched user process while preventing the helper cache from growing indefinitely. If `/var/cache/distfiles` is readable, it is passed as read-only distfiles directory. The generated or updated `Manifest` is added to SVN if it was not versioned yet, but the helper does not commit in manifest-only mode.

## Dependencies

Runtime:

```text
dev-vcs/subversion
gnome-extra/zenity
```

Zenity is started with `MESA_LOG_LEVEL=error` so harmless Mesa driver warnings do not clutter the PhpStorm tool output.

When using the installed binary from the package, PhpStorm should call `phpstorm-ebuild-svn-commit-helper` directly. Running the source `.php` file before installation additionally requires PHP CLI.

Build-time dependencies are provided by the normal `pwphpbytecode` / `pw-build-meson` package stack. The Meson configure step also checks that `svn` and `zenity` are available with `find_program(..., required: true)`.

## Mapping storage

The source-to-ebuild mapping is stored per user and machine, outside SVN:

```text
~/.config/phpstorm-ebuild-svn-commit-helper/mappings.json
```

When a source path is unknown, the helper opens Zenity list dialogs for the ebuild category and then the package directory, and saves the selected mapping.

The list is built from the `gentoo-repository-petersweeze` overlay root. The helper finds that root by walking upward from the source directory and, as fallback, from the SVN working-copy root.

## Build layout

This follows the existing `pwphpbytecode` / `pw-build-meson` source layout:

```text
meson.build
meson.options
src/meson.build.pw
src/phpstorm-ebuild-svn-commit-helper.php
```

`pw-build-meson` generates the installable `src/meson.build` during Meson configure.

## Dependency warning

If `meson.build` exists in the source tree, dependency-like lines and list blocks are compared against the source SVN revision encoded in the template ebuild filename (`_pREV`). This is safer than comparing against `BASE`, because it still catches dependency changes when source commits happened without an ebuild update.

Example: if the newest template ebuild is `foo-1.2_p12345.ebuild`, the helper compares the current `meson.build` with:

```bash
svn cat -r 12345 /path/to/source/meson.build
```

If the template ebuild has no usable `_pREV`, or if that old `meson.build` cannot be read, the helper warns and asks for confirmation before creating the new ebuild.
