I need some advice on how to structure our projects in Git. We use Java and Maven is our build tool. Maven kinda assumes all of your projects have a common ancestor eventually. Maven can also be a real drama queen when things aren't setup exactly the way the Apache foundation sets up their projects (anyone using the release plugin probably knows what I'm talking about).

We want a top level parent pom that controls plugin versions and build configuration (repo config, what artifacts to build, naming conventions, plugin versions, etc). Maven would want all of our IT projects to be in subfolders of that main project. This implies one massive Git repo for the organization.

This will make for a very noisy environment. If there are two teams working on unrelated projects, they will constantly have to pull in merges from the other team. Ideally I'd like to have one repo per project.

But that sort of clashes with the extremely hierarchal model of Maven, which demands sub-projects be sub-folders.

I need some advice on how people have reconciled these two models... thank you!

  • 2
    git submodules ? git-scm.com/book/en/Git-Tools-Submodules
    – lwm
    Commented May 20, 2013 at 9:55
  • 1
    Git-sub modules are not a preferred approach. A mono repo is not a requirement for apps sharing a common parent. We have 1000's of apps, each w/own repo with a common enterprise parent (2 actually, one w/common dependencies and a common set of plugin configurations) from another repo(s). In fact, many of our multi-module apps even have separate repository for each module. Even the Multi-module apps can consume a common sub-component from the same or another repo. All components external to it come from a repository mgr (via or from a the local repo).
    – Ian W
    Commented Jan 24, 2021 at 12:34

2 Answers 2


You have 2 options:

  1. by git way: use submodules. Here is a documentation how git manage submodules [git submodules][1]. I personally didn't use it but it looks to fit your problem.
  2. by maven way: in maven it is not mandatory that your root project (configuration) to be hierarchically the parent directory of all your projects. You can have a structure like that:
 +-- pom.xml (configuration:XXX)
 +-- pom.xml (project1:1.0-SNAPSHOT)
 +-- module11 
 !     +-- pom.xml (1.0-SNAPSHOT)
 +-- module12
       +-- pom.xml (1.0-SNAPSHOT)
 +-- pom.xml (project2:2.0-SNAPSHOT)
 +-- module21 
 !     +-- pom.xml (2.0-SNAPSHOT)
 +-- module22
       +-- pom.xml (2.0-SNAPSHOT)

configuration, project1 and project2 are on the same directory level and each one could be a git repository. When build project1 or project2 you run the maven command from project1 or project2 level and maven will try to fetch the parent (configuration) from maven repository not from parent directory. You should pay attention to versions. I would recommend in project1 or project2 to keep a reference to a parent (configuration) with a release version.

To make a release you have to do it in 2 steps: release configuration first and release project second. Project1 and project2 can evolve independently and doesn't have to have the same configuration version as a parent.

Just for special cases when you want to have both configuration and projects as SNAPSHOT versions, in project1 or project2 you can use the <relativePath> tag inside <parent> tag to point to your local path of configuration. I don't recommend this because will create problems on development environment (at least for me in Eclipse)

I apologize for my English. [1]: http://git-scm.com/book/en/Git-Tools-Submodules


Maven would want all of our IT projects to be in subfolders of that main project

No, Maven simply wants to be able to retrieve the artifacts that it needs. The best way to do this is with an artifact repository, such as Nexus or Artifactory. Each project can have its own Git repository.

We want a top level parent pom that controls plugin versions and build configuration (repo config, what artifacts to build, naming conventions, plugin versions, etc

There's your real problem. It makes sense to use a parent POM to enforce configuration, but there's no reason to combine configuration with build control. In fact, except for a stand-alone multi-module project, I'd say that it's an extremely bad idea, for just the reasons that you state (plus the fact that you'd have to build all of your projects, all of the time).

  • I'm intimately familiar with how maven works. And no, I don't want my teams building the entire codebase. Typically you would select a small number of projects and pull them out of source control. We have a nexus server to host finished artifacts, so there is no reason to build the entire codebase. And once your organization is a certain size, running on shared infrastructure saves money. Having a central configuration to do that is the only way to make sure that works, every time. Commented May 20, 2013 at 14:05
  • Dear @parsifal please have a sight at my question about creating java multi layer app stackoverflow.com/questions/49562268/… Commented Mar 30, 2018 at 11:53
  • @JonathanS.Fisher perhaps you could elaborate on your comment in a full answer? I would love to see your thoughts.
    – cptully
    Commented Mar 24, 2022 at 19:16

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.