Inspect submodule state

Before you begin

Python 3.12 or later.
Git must be installed on PATH. --repo must be an existing non-bare repository.

What this script changesRead-only Git inspection with optional locking disabled. No fetch, checkout, reset, commit, merge, or push is performed. Metadata, author information, and filenames can be private.

Set up your example

Save as git-submodule-state.py.
Open a terminal in its folder.
Run python "git-submodule-state.py" --help and prepare the listed input files.

This recipe uses your own local input or creates its own example output. Follow the setup steps below.

Download the ZIP, extract it, and open a terminal inside the extracted folder. The source file is git-submodule-state.py.

Run the script

python "git-submodule-state.py"

If your system uses python3 instead of python, use that command for Python examples. Keep paths containing spaces in quotes. Required inputs and optional settings are described in the code and setup steps.

What to expect

An uninitialized gitlink has checkout_commit=null; an existing checkout is labeled matches or different commit.

The complete script

#!/usr/bin/env python3
"""Compare tracked submodule gitlinks with existing local checkout commits without initialization or updates."""
import argparse
import sys
import json
from pathlib import Path
import os
import subprocess
from collections import Counter
from datetime import datetime, timezone

def git(repo,*arguments,allow=(0,)):
    env=dict(os.environ,GIT_OPTIONAL_LOCKS='0',GIT_PAGER='cat',GIT_TERMINAL_PROMPT='0')
    result=subprocess.run(['git','--no-pager','--no-optional-locks','-C',str(repo),*arguments],capture_output=True,timeout=60,env=env)
    if result.returncode not in allow:
        raise RuntimeError(result.stderr.decode('utf-8','replace').strip() or f'git exited {result.returncode}')
    return result.stdout

def text(repo,*arguments,allow=(0,)):
    return git(repo,*arguments,allow=allow).decode('utf-8','replace')

def main():
    parser = argparse.ArgumentParser(description='Compare tracked submodule gitlinks with existing local checkout commits without initialization or updates.')
    parser.add_argument("--repo",type=Path,default=Path("."))
    args = parser.parse_args()
    repo=Path(text(args.repo,"rev-parse","--show-toplevel").strip())
    
    for raw in git(repo,'ls-files','--stage','-z').split(b'\0'):
        if not raw:continue
        info,name=raw.split(b'\t',1);mode,recorded,stage=info.split()
        if mode!=b'160000':continue
        path=os.fsdecode(name);child=repo/path
        current=None
        if (child/'.git').exists():
            try:current=text(child,'rev-parse','--verify','HEAD').strip()
            except RuntimeError:pass
        expected=recorded.decode('ascii')
        print(json.dumps({'path':path,'recorded_commit':expected,'checkout_commit':current,'state':'not initialized' if current is None else ('matches' if current==expected else 'different commit')}))

if __name__ == '__main__':
    try:
        main()
    except (OSError, ValueError, RuntimeError) as exc:
        print(f'Error: {exc}', file=sys.stderr)
        sys.exit(1)

Open source as plain text · Download source and sample files

How it works

Compare tracked submodule gitlinks with existing local checkout commits without initialization or updates.
Arguments are explicit and expected input errors produce a message with a nonzero exit code.
Results reflect your selected local data or the specific endpoint you choose; the example illustrates the result shape.

Make it your own

Adapt the task

The ls-files --stage mode 160000 filter selects immediate submodules. Run separately inside a checkout to inspect its nested gitlinks; none are fetched or initialized.

Adjust presentation

Edit final print statements or json.dumps indentation to adjust the report layout. Keep input validation and exclusive-create file modes intact.

Change one setting at a time, run it again on sample data, and compare the output. The customization guide walks through this process.

If something goes wrong

An input or dependency is unavailable.

Git must be installed on PATH. --repo must be an existing non-bare repository.

Actual results differ from the example.

Inputs and system state determine values. Review each finding in context; a report is not proof of system health or a complete security assessment.

Reference & next steps

Git git-submodule documentation ↗

These official references explain the underlying tools. The Scriptage example and guide are original instructional content. See verification notes for what has been checked and the limits of those checks.

Copies a template for your own notes. It does not send anything.