A Practical Approach to Multi‑Project Source Code Management Using Git Submodules, Monorepo and Automation Scripts

Background – In fast‑moving development environments, many small, similar projects (e.g., weekly operational activities) quickly accumulate, leading to fragmented git repositories, duplicated resources, and heavy source trees that are difficult to maintain.

Common source‑code management schemes

Multiple independent git repositories (copy‑and‑modify).

Single git repository with all projects distinguished by folder names.

Engineering‑level solutions such as scaffolding tools, Lerna, monorepo, etc.

All of these have shortcomings: they either lack unified management, hinder independent development, or provide no advantage over npm‑style sharing.

Target solution – Combine the benefits of a single‑git code‑sharing repository with the isolation of multiple git projects. The main repository holds base configuration and shared modules, while each sub‑project is a git submodule that can be developed, built, and deployed independently.

Task breakdown

Separate the base engineering from sub‑module engineering to support independent development and builds.

Combine the main project with sub‑modules in a compositional manner.

Provide shell scripts to automate common operations (creation, initialization, building, deployment).

Apply the approach in practice.

1. Project partitioning – Using the Umi framework as the base, we reorganized the project structure so that the main project contains only common configuration and shared modules, while each sub‑project contains its own pages, mock data, router, and build output.

Umi’s convention‑over‑configuration makes it hard to change mock directories, so we dynamically load mock configurations from sub‑projects based on a command‑line argument:

const projectName = process.argv[3];
const url = '../src/pages/' + projectName + '/mock/index';
var mockData = require(url);
export default mockData.mock;

Umi can only build pages defined in its router, so we extended the build process to accept a project name and output to a project‑specific directory. A multi‑project build script iterates over all pages:

#!/bin/bash
buildAll(){
  path="$PWD/src/pages"
  dir=$(ls $path)
  for i in $dir; do
    npm run buildpro $i
  done
}
if [ "$@" = "all" ]; then
  echo 'start build all project ...'
  buildAll
else
  for arg in $@; do
    npm run buildpro $arg
  done
fi

2. Sub‑module integration – Administrators maintain the main repository plus all sub‑modules, while developers only initialize and update the sub‑modules they are responsible for. Permissions control who can push to which sub‑module.

3. Automation scripts – To hide git‑submodule complexities, we created shell scripts for creating a new sub‑project, initializing it, and installing dependencies. Example creation script (simplified):

initProject(){
  path="$PWD"
  cd $path/src/pages
  rm -rf *
  echo '初始化项目...'
  git submodule init $pname
  git submodule update $pname
  echo '开始安装依赖...'
  cd $path
  npm install
}

Practical usage – With the architecture in place, developers can run a few commands to create, build, and run projects:

npm run create
npm run build all
npm run initProject
npm run dev
npm run build

Summary and outlook – The proposed scheme successfully manages dozens of incremental projects, reduces repository size, and improves maintainability. It can also serve as a foundation for micro‑service architectures.

References

https://umijs.org/

https://git-scm.com/docs/git-submodule

Author – Gao Ying, former front‑end lead of 58 Group Information Security Department, responsible for architecture design, tooling, and front‑end research.