Git Lifecycle: Consuming a Submodule

To share (in essence) sources between two projects, it is necessary either to create

• separate git repositories, one consuming a JAR from the second,
• a proper project and a submodule that the project consumes as-is from the second project (which is treated as a submodule).

The first case is classic and ancient as well as perfectly understood by all git users. The second is an innovation that might serve for sharing documents on a larger scale with design project for which the git repository is for version control and safekeeping.

A scenario: consume test fodder from a documentation project

Let's imagine a design project that wishes to specify a data document as a statement of features and requirements when consumed by a code project in its testing. Let's call this repository https://github.com/foo. A committee of the engineering department creates and maintains design documents including requirements, features, plans and, most importantly, data files in this git project.

Let's posit a file, gold-standard.dat in the design project repository on the path gold-fodder. Documents containing feature lists, requirements and other specifications will reside in whatever form chosen for this work, however, this data is going to be consumed from a Java code project, so it will live in a place that best accommodates that use (read on).

Imagine a consuming project, https://github.com/bar that implements software to specifications apearing in repository https://github.com/foo. Because this project produces a software binary, it is a code project (as opposed to a purely design project).

We imagine that the code project consumes gold-standard.dat from JUnit test code on the path src/test/com/acme/gold/GoldStandardTests.java. It's not the code project that determines what's in the data, but only to incorporate it in JUnit tests to monitor required coverage, regression, etc.

Commands to consume, update and maintain gold-standard.dat

There is nothing special for the design project to do differently from usual git maintenance (git add, git commit, git push, etc.). In project foo's repository, where the project owner and/or project managers store their documents, it looks like this:

foo
├── (various design files)
└── gold-fodder
    └── gold-standard.dat                         # (...where this is created and maintained)

However, the consuming code project will need to incorporate formally the design project:

$ cd src/test/resources
$ git submodule add https://github.com/foo

Whereupon it will have a filesystem ressembling

bar
├── pom.xml
└── src
    ├── main
    └── test
        ├── fodder
        │   └── foo                               # (design project)
        └── java
            └── com
                └── acme
                    └── GoldStandardTests.java

To get the file, gold-standard.dat, that supposedly supplied by the design project to the code project:

$ git submodule update --init --recursive         # (the first time)
$ git submodule update --recursive                # (subsequent times)

git will not keep this file up-to-date. Thus, every time the developer and owner of project bar hears that gold-standard.dat has changed, the second command above must be rerun.

What it looks like in the filesystem when up and running...

Once the submodule is created and updated, assuming privileges satisfied, the code project will appear thus:

bar
├── pom.xml
└── src
    ├── main
    └── test
        ├── fodder
        │   └── foo                               # (design project and files including...)
        │       ├── (various design files)
        │       └── gold-fodder
        │           └── gold-standard.dat         # (...our sought-after test fodder)
        └── java
            └── com
                └── acme
                    └── GoldStandardTests.java

...and GoldStandardTests.java will be able to open and read the data file something like this:

FileInputStream inputStream = new FileInputStream( "src/test/fodder/foo/gold-fodder/gold-standard.dat" );
etc.