beman-submodule

A pseudo-submodule tool for vendoring Git repositories in Beman projects.

What is beman-submodule?

beman-submodule provides some of the features of git submodule, adding child git repositories to a parent git repository, but unlike with git submodule, the entire child repo is directly checked in, so only maintainers, not users, need to run this script. The command line interface mimics git submodule's.

Installation

pip install beman-submodule

Or with uv:

uv tool install beman-submodule

Usage

Adding a beman submodule

beman-submodule add https://github.com/bemanproject/infra.git

This will clone the repository and create a .beman_submodule file tracking the remote and commit.

You can also specify a custom path:

beman-submodule add https://github.com/bemanproject/infra.git infra/

Updating beman submodules

Update all beman submodules to match their .beman_submodule configuration:

beman-submodule update

Update all beman submodules to the latest from upstream:

beman-submodule update --remote

Update only a specific submodule:

beman-submodule update --remote infra/

Checking status

Show the status of all beman submodules:

beman-submodule status

A + prefix indicates the submodule contents differ from the configured commit.

How does it work?

Along with the files from the child repository, it creates a dotfile called .beman_submodule, which looks like this:

[beman_submodule]
remote=https://github.com/bemanproject/infra.git
commit_hash=9b88395a86c4290794e503e94d8213b6c442ae77

Updating to a specific commit or changing the remote URL

Edit the corresponding lines in the .beman_submodule file and run beman-submodule update to update the state of the beman submodule to the new settings.

Allow untracked files

If you need to add local files alongside the vendored content, use:

beman-submodule add --allow-untracked-files https://github.com/example/repo.git path/

This adds allow_untracked_files=True to the .beman_submodule config, preserving local files during updates.

CI Integration

Add this job to your CI workflow to ensure beman submodules are in a valid state:

  beman-submodule-test:
    runs-on: ubuntu-latest
    name: "Check beman submodules for consistency"
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Install beman-submodule
        run: pip install beman-submodule
      - name: beman submodule consistency check
        run: |
          (set -o pipefail; beman-submodule status | grep -qvF '+')

This will fail if the contents of any beman submodule don't match what's specified in the .beman_submodule file.

Development

This project uses uv for development:

# Install dependencies
uv sync --group dev

# Run tests
uv run pytest

# Run linter
uv run ruff check .

# Format code
uv run ruff format .

License

Apache-2.0 WITH LLVM-exception