Cross-Repository Workflow

Oidis multi-repo projects require code synchronization between the dependencies/ folder (where you develop with live server context) and standalone dependency clones (where you commit). This page documents the complete workflow in both directions, common pitfalls, and how to use Claude Code to automate the process.

When This Applies

This workflow is relevant whenever you edit code inside a dependencies/ subdirectory and need to commit those changes to the dependency's own repository:

• Separate GUI repos — Hub, Home, Studio (most common case). See Separate GUI Repository for why these repos are split.
• CORE dependency changes — fixing or extending io-oidis-commons, io-oidis-gui, io-oidis-services, io-oidis-usercontrols, io-oidis-localhost, io-oidis-hub, or io-oidis-hub-gui while working on a solution project.
• Any multi-repo scenario — any project where you edit code inside dependencies/<name>/ and need that code committed upstream.

note

If your project keeps the frontend under Gui/ in the same repository (the single-repo pattern), this workflow does not apply to you. It is only relevant for projects with dependencies declared in package.conf.jsonp that are separate git repositories.

Synchronization Directions

There are two directions of file transfer between dependencies/ and a standalone clone. Understanding both is essential for an efficient workflow.

Forward Sync: dependencies/ → Standalone Clone

The primary workflow. You developed in the dependencies/ context (with a running backend, full tsconfig aliases, and hot reload) and need to commit your changes in the dependency's own repository.

Complete step-by-step:

1. Verify branch alignment — check that your standalone clone is on the correct feature branch (not master or develop).
2. Pull latest — run git pull in the standalone clone to avoid overwriting someone else's recent work.
3. Detect changes — identify which files you modified in dependencies/<name>/. Use git diff or a directory comparison tool.
4. Transfer source files — copy only source files (.ts, .scss, .html, .bsdesign, .jsonp data files, unit tests). Skip all generated files.
5. Control build — run oidis rebuild in the standalone clone. If dependencies of the clone changed, run oidis install first.
6. Handle build failures — if the build fails, fix the issues in the standalone clone and transfer the fixes back to dependencies/ (see Reverse Sync below).
7. Verify pre-commit hooks — hooks only run in the standalone clone, not inside dependencies/. They validate TypeScript compilation, linting, and copyright headers.
8. Commit — commit to the feature branch using the standard format: [TICKET-ID] Description.
9. Push — push to the remote. Integrators handle merging to develop and stable branches.

Reverse Sync: Standalone Clone → dependencies/

Used when you need to bring changes from the standalone clone back into your dependencies/ working context. Common scenarios:

• The control build in the standalone clone required fixes that need to go back to your working context.
• Someone else committed changes and you need them in dependencies/ without running a full oidis install.
• You want to avoid the overhead of oidis install when you know exactly what changed.

Step-by-step:

1. Transfer source files — copy source files from the standalone clone into dependencies/<name>/.
2. Verify parent project — confirm that the parent project (the one that owns dependencies/) still builds correctly with the updated files.
3. Continue development — resume working in the dependencies/ context.

Reverse sync bypasses oidis install

Manually copying files into dependencies/ skips all Builder modifications — tsconfig aliases, generated package files, and dependency resolution. Only do this when you have full control over what changed and are confident no generated files need regeneration. When in doubt, run oidis install instead.

Dependency Version Management

Understanding how the Builder manages dependencies is essential for avoiding version mismatches during cross-repo work.

Pinning to Branch, Tag, or Commit

Dependencies in package.conf.jsonp specify exactly what version to install:

"dependencies": {
    "io-oidis-commons": "git+https://gitlab.com/oidis/io-oidis-commons.git#develop",
    "io-oidis-gui":     "git+https://gitlab.com/oidis/io-oidis-gui.git#2026.0.1"
}

The #develop suffix pins to a branch, #2026.0.1 pins to a tag. The Builder clones exactly that ref during oidis install.

Uniform Dependency Tree

The Builder enforces a uniform dependency tree — each dependency can appear at most once in the entire tree (Java-style). If two packages declare the same dependency at different versions, the install fails. This ensures consistency but means all packages in the tree must agree on shared dependency versions.

Local Development with dir+

For active development, you can override a git dependency with a local path:

// private.conf.jsonp — never committed
"dependencies": {
    "io-oidis-commons": "dir+D:/workspace/io-oidis-commons"
}

This tells the Builder to use the local clone directly instead of cloning from git. Changes in the local clone are immediately visible after oidis install.

Branch Mismatch

If package.conf.jsonp declares git+url#develop but your standalone clone is on feature/OID-42, you are working against different baselines. The code in dependencies/ (installed from develop) may differ from what is in your standalone clone (on a feature branch). Always verify that your standalone clone branch matches what you intend to target.

Package Lock File

During every build, the Builder generates build/target/package.lock.json — a complete snapshot of the resolved dependency tree. This file records every dependency's name, version, source URL, git branch/tag, and the exact git SHA that was installed.

The lock file serves a similar purpose to npm's package-lock.json, but is designed specifically for the Oidis Builder's dependency model. Its primary use cases:

• Project baseline — lock the entire dependency tree to a known-good state for reproducible builds
• Debugging historical versions — recreate the exact dependency state from a past release
• Audit trail — verify which exact commit of each dependency was included in a build

Installing from a baseline lock:

To restore a project to a locked baseline state, manually copy package.lock.json from build/target/ into the project root and run oidis install. The Builder detects the lock file, verifies all entries, and installs each dependency at the exact SHA recorded in the lock.

# Restore from a baseline lock
cp build/target/package.lock.json ./package.lock.json
oidis install

Using the lock file for sync verification

The lock file's git SHA entries can help detect whether dependencies/ has diverged from what was originally installed. Compare the SHA in the lock file with git rev-parse HEAD in dependencies/<name>/ — if they differ, someone modified the dependency after install (either via manual edits or reverse sync). Note that this only tells you about divergence from the install point, not about the state of the standalone clone or remote.

Three-Way Merge Pitfalls

The most dangerous aspect of cross-repo work is the potential for three-way merge conflicts. These occur when the code in dependencies/, the standalone clone, and the remote repository have diverged.

Standalone Clone Behind Remote

• Symptom: your transfer overwrites someone else's recent commits because your standalone clone does not have them.
• Detection: run git fetch && git status in the standalone clone before transferring. If it reports "behind origin", you need to pull.
• Resolution: pull first, then transfer your changes. Resolve conflicts if the same files were modified.

dependencies/ Folder Behind (Not Reinstalled)

• Symptom: you are editing an old version of the dependency. The standalone clone (or remote) has newer code that is not in your dependencies/ folder.
• Detection: compare the dependency branch/tag in package.conf.jsonp with what is actually checked out in dependencies/<name>/. Run git log --oneline -5 in both locations to compare HEAD.
• Resolution: run oidis install to refresh the dependency, then re-apply your changes on top of the updated code.

Quick version check

Run git log --oneline -1 in both dependencies/<name>/ and the standalone clone. If the commit hashes differ, the two locations are out of sync.

Concurrent Changes in Multiple Projects

• Symptom: you edited the same dependency from two different parent projects (e.g., both io-oidis-hub and io-oidis-home have changes to io-oidis-commons).
• Detection: the standalone clone has uncommitted or unpushed changes when you try to transfer from the second parent.
• Resolution: commit or stash the standalone changes from the first parent before transferring from the second. Then merge or rebase as needed.

Wrong Branch in Standalone Clone

• Symptom: changes are committed to master or develop instead of a feature branch, or to the wrong feature branch entirely.
• Detection: always run git branch in the standalone clone before any transfer.
• Resolution: create or switch to the correct feature branch before committing.

Integration Risk

Committing to the wrong branch — especially develop or master — can break the integration pipeline. Only integrators merge to develop and stable branches. Always verify your branch before committing. If you accidentally committed to the wrong branch, contact an integrator immediately to revert the damage.

Post-Transfer Checklist

Use this checklist after every forward sync to ensure nothing is missed:

1. ☐ Standalone clone is on the correct feature branch
2. ☐ Latest changes pulled from remote
3. ☐ Only source files transferred (not generated files)
4. ☐ Control build passes (oidis rebuild; or oidis install + rebuild if dependency tree changed)
5. ☐ If build failed — fixes made and transferred back to dependencies/
6. ☐ Pre-commit hooks pass (TypeScript compilation, lint, copyright headers)
7. ☐ Code reviewed in standalone context
8. ☐ Commit to feature branch: [TICKET-ID] Description
9. ☐ Push to remote — integrators handle merge to develop/stable

Files to Transfer vs. Files to Skip

General Rule

Transfer source files that you wrote. Skip everything the Builder generates or manages.

Transfer ✅	Skip ❌
source/typescript/**/*.ts	tsconfig.json (generated by Builder)
source/html/**/*.html	package.json (generated from package.conf.jsonp)
source/html/**/*.bsdesign	webpack.config.js (generated SCSS alias file)
resource/sass/**/*.scss	.idea/ directory (IDE-specific)
resource/data/**/*.jsonp	dependencies/ subdirectory
test/unit/typescript/**/*.ts	build/, build_cache/
bin/project/configs/*.jsonp	node_modules/
package.conf.jsonp (if changed)	Any *.compiled.d.scss

tip

When in doubt, ask: "Did I write this file, or did the Builder generate it?" If the Builder generated it, do not transfer it — it will be regenerated correctly by oidis install or oidis rebuild in the standalone clone.

For GUI-specific file rules, see the Files to Transfer vs. Files to Skip table in the Separate GUI Repository page.

Recommended Tools

IntelliJ Directory Diff

Use IntelliJ's built-in Directory Diff (View → Compare with... or right-click a folder) to visually compare dependencies/<name>/source/ with the standalone clone's source/. This lets you selectively transfer individual files while reviewing each change.

Beyond Compare

For more advanced comparisons, Beyond Compare supports folder-level diffing with filters. Set up a filter to exclude generated files (tsconfig.json, package.json, webpack.config.js, *.compiled.d.scss, node_modules/, build/).

Claude Code /sync-dependency Skill

The /sync-dependency skill automates the forward sync workflow:

• Detects changed files in dependencies/<name>/
• Checks branch alignment and merge risks in the standalone clone
• Transfers source files selectively (skips generated files)
• Runs the control build and helps handle failures
• Offers reverse sync for build fixes
• Remembers clone paths across sessions

Usage:

/sync-dependency io-oidis-hub-gui
/sync-dependency io-oidis-commons --target=D:/workspace/io-oidis-commons
/sync-dependency io-oidis-hub-gui --reverse

Review Detection

The /review skill includes a check for unsynchronized dependency changes. If you have uncommitted modifications in any dependencies/ subdirectory, the review warns you about pending transfers that may need to be synced to standalone clones.

---

See also: Separate GUI Repository | Version Control | Configuration Reference | Claude Code Integration