Multi-Root Projects: Multiple Git Repositories in One PhpStorm Window

1. The problem: module development isolated from the Magento core

A custom Magento module often lives in a separate Git repository, for example under src/app/code/Mironsoft, while the actual Magento core sits in a different repository or as a Composer dependency. Opening only the module directory as a project leaves PhpStorm without context for the core classes the module extends or plugs into. This missing context is especially painful with preference overrides or deep plugin chains, since you constantly have to switch back and forth between module and core to trace the actual inheritance chain.

The result is incomplete code completion, broken navigation to interface definitions, and PhpStorm warnings about supposedly unknown classes that actually exist in the core. A second, separate PhpStorm window for the core only partially solves the navigation problem, because search and refactoring then no longer work across the project. You end up manually copying class names between two windows, which quickly becomes error-prone during longer research tasks and effectively defeats the whole point of an IDE's integrated code navigation.

2. The core idea: Attach Directory as Content Root

PhpStorm lets you add further directories to an existing project as additional content roots, via File, Open, and choosing Attach when opening another directory. Each content root appears in the project tool window as its own root node, but keeps its own directory structure and, if present, its own .git directory.

Technically, this does not merge repositories, it creates a single PhpStorm project that references several independent filesystem roots. The main project's .idea configuration merely stores the paths to the additional roots, while each root directory remains fully self-contained.

<!-- .idea/modules.xml in the main project -->
<module fileurl="file://$PROJECT_DIR$/modul.iml" filepath="$PROJECT_DIR$/modul.iml" />
<module fileurl="file://$PROJECT_DIR$/../magento-core/core.iml" filepath="$PROJECT_DIR$/../magento-core/core.iml" />

3. Setting up a multi-root project step by step

The starting point is the module repository as the main project. Via File, Open, selecting the Magento core directory, and choosing Attach in the following dialog, the core is added as a second content root instead of opening a new window. PhpStorm then indexes both directory trees and builds a shared symbol table. The dialog explicitly asks whether the directory should open as a new window or be attached to the existing project, a point where many developers pick the wrong option by mistake and then wonder why two separate windows appear.

For large core repositories, it pays to first mark unnecessary core areas, such as test directories or vendor subfolders, as Excluded under Settings, Directories, to shorten indexing time. Once indexing finishes, Go to Declaration, Find Usages, and code completion all work seamlessly across both roots. With a full Magento core checkout, the first indexing pass can easily take several minutes depending on machine performance, so it makes sense to kick it off deliberately during a break rather than in the middle of active work.

4. Managing separate VCS history per root

PhpStorm automatically detects that each content root brings its own .git directory and registers multiple VCS roots within the same project accordingly. In the commit dialog, changes are grouped by their respective repository, so a commit never accidentally mixes changes from both repositories.

The Local History, Annotate, and Show History tools also work correctly per file within its own repository, so blame for a core file is never mistaken for the module repository. The VCS dropdown in the toolbar automatically shows the matching branch name of the relevant root for the active editor tab.

# Both roots remain independent Git repositories
src/app/code/Mironsoft/.git      # own module repository
../magento-core/.git             # Magento core repository
# git status must be run separately inside each root

5. Navigation and search across the whole project

The real payoff of a multi-root project shows up with Find Usages: running it on an interface method in the core also lists every implementation and call site in the module repository, even though both live in separate Git repositories. Without the additional content root, that search would silently end at the module directory boundary.

Search Everywhere and Go to Class likewise search all registered roots at once, which saves time especially when looking up Magento core interfaces while developing your own plugin. Structure and type hierarchy views also work across repositories, which is particularly valuable with complex inheritance spanning core and module.

6. Composer autoloading and PHPStan in a multi-root context

For code intelligence to actually work, PhpStorm must resolve the Composer autoload configuration correctly across both roots. Usually it is enough if the core root brings its own composer.json with a vendor directory, from which PhpStorm derives the namespace mapping automatically, as long as Settings, PHP, Composer points at the right composer.json.

For PHPStan analysis, note that the invocation still targets only the module directory, for example bin/analyse app/code/Mironsoft/SeoSuite --level=5, while the additional content root serves purely for IDE navigation and is not automatically included in every analysis run.

7. Pros and cons compared to separate windows

The biggest advantage of a multi-root project is seamless navigation and search across repository boundaries, combined with a single window environment instead of two parallel PhpStorm instances each consuming their own memory. On developer laptops with limited RAM, that makes a noticeable difference.

The downside shows up during indexing: a large Magento core root significantly extends the initial indexing time, and Search Everywhere results more often include core hits that were not actually intended. Anyone working exclusively on the module and only occasionally needing the core may be better served by two separate windows with a deliberate window switch.

8. Removing a content root again without deleting files

An added content root can be removed from the project at any time via Settings, Directories, and the Detach Directory button. Only PhpStorm's internal project references are removed, the files and the associated Git repository on disk remain completely untouched.

This is especially handy when the core root is only needed temporarily for a single refactoring task, for example to check an interface signature across many callers, after which it is removed again to keep the indexing load low for everyday work.

9. A recommendation for typical Magento team setups

For developer teams that regularly switch between their own module code and Magento core internals, for example with deep plugin chains or complex preference overrides, a permanent multi-root project is usually the more productive choice. The one-time indexing cost pays for itself quickly through the window switches saved. In practice it works well not to mandate this decision project-wide but to leave it to each developer individually, since personal work habits and the performance of one's own machine matter here just as much as the raw project structure.

For pure frontend work on Hyva templates or isolated module development without frequent core references, the extra content root rarely pays off. Here a lean single-project setup with a targeted, temporary attach as needed remains the more practical solution.

10. Summary

11. FAQ: Multi-Root Projects in PhpStorm: The Essentials at a Glance