Skip to content
Arxo Arxo

Git History Integration

Git History Integration

Section titled “Git History Integration”

When you enable git history for the SCC metric, Arxo loads your repository’s commit data and uses it to rank files inside each cycle. That gives you a refactor priority: fix the files that are both central to the cycle and change most often.

For an overview of circular dependencies, see Circular Dependencies. For the detailed per-cycle view, see Cycle Microscope.

What Changes When Git History Is On

Section titled “What Changes When Git History Is On”
Without git historyWith git history
Cycle details list nodes and edges onlyEach node gets churn (commits touching that file)
No priority signalEach node gets hotspot_score (churn × centrality)
You pick refactor targets by guessworkSort by hotspot_score — fix the top ones first

Churn = total number of commits that touched that file (over the analyzed history).
Hotspot score = churn × centrality (betweenness within the cycle). High score = high impact when you refactor that file.

How to Enable

Section titled “How to Enable”

In your metric config, set use_git_history: true for the SCC metric:

metrics:
  - id: scc
    config:
      use_git_history: true

Runs that use this config will load git history (slower) and fill churn and hotspot_score in the Cycle Microscope node table.

Performance

Section titled “Performance”

Loading git history adds noticeable time to analysis, especially on large repos. Use it when you’re actively refactoring cycles and need priority; for quick CI checks, you can leave it off.

  • Cold run (no cache): Full analysis + git can be much slower than analysis alone.
  • Warm run (with cache): Cache can avoid recomputing the graph; git may still be loaded each run depending on cache policy.

Enable caching to speed up repeated runs.

Troubleshooting

Section titled “Troubleshooting”

Churn and hotspot_score are always zero

Section titled “Churn and hotspot_score are always zero”
  • Cause: Git history isn’t loaded for the run.
  • Fix: Set use_git_history: true in the SCC metric config (see above).
  • Check: Run with ARCH0_SCC_DEBUG=1 and look for a line like [scc] use_git_history=true git_history=Some in the output.
Terminal window
ARCH0_SCC_DEBUG=1 arxo analyze

Git history is None even with use_git_history: true

Section titled “Git history is None even with use_git_history: true”
  • Cause: Repo might not be a git repo, or arxo might not be run from the repo root, or git might be unavailable.
  • Fix: Run from the project root and ensure the directory is a git repository. If you use a non-standard git setup, check that arxo can see the same repo.

Summary

Section titled “Summary”
  • Enable: metrics[].config.use_git_history: true for the scc metric.
  • Use: In the Cycle Microscope, sort the node table by hotspot_score and refactor the top nodes first.
  • Trade-off: Better refactor priority in exchange for slower runs; use caching when possible.

Next Steps

Section titled “Next Steps”