Single vs. Multi-Module Repositories
A Git-enabled application can have a repository to itself, or share one with other applications. The choice is made when you create or connect the application, and it affects how branches, deletion, and cloning behave afterwards — so it is worth making deliberately.
The two structures
A single-module repository contains one application. It is straightforward, and it is the right default. Branches belong to that application alone, and deleting the application affects nothing else.
A multi-module repository holds several applications in one repository, each in its own folder. The first time you create an application in one, that repository becomes the default location for the workspace's other multi-module applications, and the Remote Url is pre-filled for subsequent applications.
What differs in practice
| Single-module | Multi-module | |
|---|---|---|
| Applications per repository | One | Several, each in its own folder |
| Branch namespace | Belongs to the one application | Shared across every application in the repository |
| Naming | The Koodisi name is independent of the repository | The Koodisi name must match the application's folder name in the repository |
| Deleting | Removes the application from the workspace only | Offers Remove (non-destructive) and Delete (commits file deletion), which can affect other applications |
| Cloning | Clone the repository | Specify which application you are cloning |
| Adding another application | Use a new repository | Clone again under a different name, or create a new multi-module application against the same repository |
The shared branch namespace is the consequence most teams meet first: a branch in a multi-module repository exists for every application in it, and an application may exist on some branches and not others. When it does not exist on the branch you checked out, Koodisi reports Application missing from active branch and offers an Active branch list.
Choosing
Prefer a single-module repository unless you have a specific reason not to. Reach for multi-module when:
- Several applications are released together. One repository means one branch and one pull request covering a coordinated change.
- Applications share components you want versioned alongside them.
- The team is large enough that separating modules within one repository is easier to administer than many repositories.
Stay with single-module when:
- Applications are released independently. Separate repositories mean one application's branch activity never touches another's.
- The project is small or single-purpose.
- You want deletion to be safe. In a single-module repository there are no repository-level dependencies to break, which is why no Remove option is offered — deletion is local-only.
In a multi-module repository, deleting an application can remove tracked files and affect other applications that share paths. Review dependencies first, and use Remove when you only want it out of your workspace. See Deleting Git Applications.
Related topics
- Creating a Git-Enabled Application — where the choice is made
- Cloning Git Applications — cloning from a multi-module repository
- Deleting Git Applications — how deletion differs between the two