Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/seart-group/git-submodule-maven-plugin
Plugin used for updating Git submodules in Maven projects
https://github.com/seart-group/git-submodule-maven-plugin
cicd git git-submodules java java-8 jgit maven maven-plugin mit-license status submodule update
Last synced: 5 days ago
JSON representation
Plugin used for updating Git submodules in Maven projects
- Host: GitHub
- URL: https://github.com/seart-group/git-submodule-maven-plugin
- Owner: seart-group
- License: mit
- Created: 2024-07-22T12:19:42.000Z (2 months ago)
- Default Branch: master
- Last Pushed: 2024-09-17T09:26:37.000Z (16 days ago)
- Last Synced: 2024-09-25T20:47:59.669Z (8 days ago)
- Topics: cicd, git, git-submodules, java, java-8, jgit, maven, maven-plugin, mit-license, status, submodule, update
- Language: Java
- Homepage:
- Size: 120 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
# Git Submodule Maven Plugin · [](https://github.com/seart-group/git-submodule-maven-plugin/actions/workflows/deploy.yml) [](https://central.sonatype.com/artifact/ch.usi.si.seart/git-submodule-maven-plugin) [](https://javadoc.io/doc/ch.usi.si.seart/git-submodule-maven-plugin) [](https://github.com/seart-group/git-submodule-maven-plugin/blob/master/LICENSE)
This plugin is used to initialise `git` submodules in Maven projects. An absolute life-saver when performing releases.
## Rationale
When working with Maven projects that have `git` submodules, it is often necessary to clone the submodules before
building. This is especially true when performing releases, as the submodules aren't initialised by the
`maven-release-plugin` when building in a sandbox. This is a problem we've faced regularly in the past, most notably
with our [java-tree-sitter](https://github.com/seart-group/java-tree-sitter) project, and more recently with
[jcloc](https://github.com/seart-group/jcloc). The only [solution](https://stackoverflow.com/q/6938142/17173324)
proposed by the community involved the use of the `exec-maven-plugin` to run a recursive initialisation and update of
submodules within a project. Although viable, frequently copying and pasting the same configuration across projects
tends to get annoying after the first few times. This is without mentioning the technical debt that would be incurred by
having to maintain the same configuration in multiple projects. This project was born out a necessity to provide a more
Maven-like, drop-in solution to the described problem.
## Requirements
* Java 8 or later
* Maven 3.6.3 or later
> [!NOTE]
> Although it operates on Git submodules, this plugin doesn't require `git` to be installed on the system. Instead, it
> uses the Eclipse [JGit](https://www.eclipse.org/jgit/) library to interact with the VCS through Java. As a result, the
> plugin will still work in containerised environments such as Docker containers and CI/CD pipelines.
## Usage
Add the following to the `plugins` section of your `pom.xml`:
```xml
ch.usi.si.seart
git-submodule-maven-plugin
1.1.0
```
## Goals
### `status`
Equivalent to running `git submodule status --recursive`. Given that this goal only lists the status of the submodules
in the project, its primary use is for debugging. It is not bound to any lifecycle phase by default. That being said,
you can execute it directly from the command line:
```shell
mvn ch.usi.si.seart:git-submodule-maven-plugin:status
```
### `update`
Equivalent to running `git submodule update --init --recursive`. Recursively initialises and updates all submodules in
the project. To use this goal in your build, write your plugin definition as follows:
```xml
ch.usi.si.seart
git-submodule-maven-plugin
1.1.0
update
```
The default execution `phase` of this goal is `initialize`, but you can change it according to your needs.
## Configuration
At the moment, the plugin supports the following configuration options:
| Configuration | Default Value | Description |
|-------------------|---------------------------|--------------------------------------------------|
| `skip` | `false` | Skips the execution of the plugin. |
| `verbose` | `false` | Print additional execution information. |
| `dotGitDirectory` | `${project.basedir}/.git` | The path to the `.git` directory in the project. |
## FAQ
### How can I request a feature or ask a question?
If you have ideas for a feature that you would like to see implemented or if you have any questions, we encourage you to
create a new [discussion](https://github.com/seart-group/git-submodule-maven-plugin/discussions). By initiating a discussion, you can engage with the community and our
team, and we will respond promptly to address your queries or consider your feature requests.
### How can I report a bug?
To report any issues or bugs you encounter, create a [new issue](https://github.com/seart-group/git-submodule-maven-plugin/issues). Providing detailed information about
the problem you're facing will help us understand and address it more effectively. Rest assured, we're committed to
promptly reviewing and responding to the issues you raise, working collaboratively to resolve any bugs and improve the
overall user experience.
### How do I contribute to the project?
Refer to [CONTRIBUTING.md](/CONTRIBUTING.md) for more information.