repo-fix/README.md

5.2 KiB

repo-fix

Fix Dandaedre Gitea submodule URLs after cloning, pulling, or syncing:

  • .gitmodules uses HTTPS for CI: https://proxy.dandaedre.com/gitea/Beffroi/reportist.git
  • .git/config uses SSH locally: git@git.dandaedre.com:Beffroi/reportist.git
  • .git/modules/**/config uses the same SSH format for submodule remotes (url and pushurl) and nested submodule URL entries.

Requires Python 3.10 or newer and Git on your PATH. No runtime pip packages are needed; the script uses the Python standard library and Git's config commands.

Preview the changes, then apply them:

python3 fix_submodules.py /path/to/repository --dry-run
python3 fix_submodules.py /path/to/repository

The project follows semantic versioning and currently reports version 0.1.0:

python3 fix_submodules.py --version

The repository defaults to the current directory, and may also be a directory inside a working tree. Run the script again whenever a pull or git submodule sync changes the URLs. Repeated runs are safe. Dry runs do not write files.

Recognizes HTTP(S), SSH, Git protocol, and SCP-style URLs on dandaedre.com, git.dandaedre.com, and proxy.dandaedre.com. Old URLs such as git@dandaedre.com:Beffroi/reportist.git are corrected. Repository paths and .git suffixes are preserved; the proxy's /gitea/ prefix is translated.

Missing local URL entries are added from .gitmodules. Existing local URLs retain their own repository paths. Other hosts and relative URLs are skipped. Unrelated configuration, including active, is preserved.

Works with .git directories and pointer files, including linked worktrees (whose local config is shared). Existing configs under Git's modules directories are scanned recursively, including nested and deinitialized submodules. Their remotes (including origin) are repaired; the selected repository's own remotes are unchanged. Nothing is fetched. Nested working-tree .gitmodules files are not edited; run the script inside those submodules to normalize their declarations as well.

Commit .gitmodules changes for CI. Local config changes are not committed. After fixing URLs, initialize submodules with:

git -C /path/to/repository submodule update --init --recursive

Run tests:

python3 -m unittest discover -s tests -v

The unit suite includes a small deterministic fuzz test and malformed-value cases for URL parsing. They are intended to catch crashes and unsafe path shapes, not to replace a dedicated fuzzer.

For the same coverage check as CI, install the pinned tools and run:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-ci.txt
.venv/bin/coverage run -m unittest discover -s tests -v
.venv/bin/coverage report

Branch coverage must remain at or above 80%. This deliberately modest floor keeps the check useful without forcing low-value tests.

Jenkins test CI

The Jenkinsfile uses the rust_no_docker agent from the Ravenous pipeline. Configure a Jenkins Pipeline from SCM (or a multibranch pipeline) for this repository with script path Jenkinsfile. The agent needs python3 and git on PATH and network access to PyPI, vulnerability data, and the Gitea HTTPS proxy. No uv or Docker is required; CI creates isolated virtual environments and installs the pinned tools. Use the Gitea webhook URL from the Jenkinsfile if your Jenkins Gitea integration is configured at that address.

Every build runs the unit tests with coverage. Before testing, it runs two small supply-chain gates: pip-audit 2.10.1 fails on known vulnerabilities or dependency-collection errors, and pip-licenses 5.5.5 allows only MIT-licensed installed application packages. The CI environment also pins coverage 7.16.1 and setuptools 80.9.0 in requirements-ci.txt. Run the gates locally with:

.venv/bin/pip-audit --strict .
.venv/bin/pip-licenses --python=.venv-app/bin/python

The audit needs network access for package resolution and current advisory data. The license gate inspects the isolated application environment; update the explicit allow-list only after reviewing a new dependency. The project has no runtime dependencies today. These checks do not analyze the standard library, Git, malicious packages, provenance, or undisclosed vulnerabilities; no broader hardening tools are in scope.

By default, CI also shallow-clones Ravenous/ravenous_roll20.git through the HTTPS proxy into a temporary directory and verifies dry-run safety, both URL formats, repeatability, recovery after git submodule sync, and correction of the old SSH hostname. The clone is removed after the test. It does not fetch submodules or run code from Ravenous; SSH connectivity and recursive submodule downloads are not tested.

Run the same network test locally:

python3 -m unittest discover -s integration -v

The HTTPS clone URL corresponds to git@dandaedre.com:Ravenous/ravenous_roll20.git and avoids requiring an SSH key for this CI test. If authentication is required, configure Git credentials on the agent; prompts are disabled. Clone failures fail the build. Disable the RUN_CLONE_TEST build parameter for an offline unit-test-only run.

This pipeline only checks out and tests. It does not publish artifacts, send checks, push commits, or deploy files. Test results appear in the console log.