Add a shared Railblocks repo (e.g. blocks-airtable, blocks-attio) as a git submodule inside a client repo, configure automatic updates, and set up the correct pull/push workflow. Use when a team member wants to include a blocks repo as a subdirectory of a client repo, add a git submodule, or configure submodule auto-update behavior.
Add a shared Railblocks repo as a git submodule inside a client repo and configure it for automatic updates.
.code-workspace file.Both can coexist. A block can be a submodule in one client repo and a workspace folder in another.
From the root of the client repo:
git submodule add https://github.com/railblockscom/<block-name>.git <block-name>
This clones the block repo into <block-name>/, creates , and stages both.
.gitmodulesgit add .gitmodules <block-name>
git commit -m "Add <block-name> as git submodule"
git push
The commit pins the submodule to a specific commit hash. This is intentional — it means the client repo always references a known-good version of the block.
Run this once per machine (applies to all repos globally):
git config --global submodule.recurse true
What this does: git pull, git checkout, and git switch will automatically update submodules to match the pinned commit. Without this, submodules can silently fall behind after a pull.
Submodules pin to a specific commit. Updating the pin is a two-step process:
When the block repo has new commits on main:
# From the client repo root
git submodule update --remote <block-name>
This checks out the latest commit from the block's tracked branch (default: main). The submodule directory now has newer code, and git status will show <block-name> as modified.
Always commit and push the updated submodule reference. Otherwise only your local machine has the update and other team members will stay on the old version.
git add <block-name>
git commit -m "Update <block-name> submodule"
git push
Pull latest block and push the updated pin:
git submodule update --remote <block-name> && git add <block-name> && git commit -m "Update <block-name> submodule" && git push
When cloning a repo that already has submodules:
git clone --recurse-submodules <repo-url>
Or if already cloned without submodules:
git submodule update --init --recursive
With submodule.recurse true set globally, subsequent git pull commands will handle submodule updates automatically.
Submodule shows as modified after pull but you didn't change it: This means someone updated the submodule pin. Run git submodule update to sync your local checkout to the pinned commit.
Detached HEAD inside submodule: This is normal. Submodules check out a specific commit, not a branch. If you need to make changes to the block, cd into it and work on a branch there, push from inside, then update the pin from the parent repo.