Managing Shared Code Across Repositories with Subtree

Advanced20 min

Use git subtree to embed and synchronize shared libraries or components across multiple repositories without submodule complexity.

Prerequisites

-Git installed
-Two or more repositories (a main project and a shared library)
-Push access to both repositories

Steps

Add a remote for the shared library

Add the shared library repository as a named remote so you can reference it in subtree commands.

$ git remote add shared-ui https://github.com/org/shared-ui.git

Add the subtree to your project

Pull the shared library into the lib/shared-ui directory. The --squash flag collapses the library's history into a single merge commit.

$ git subtree add --prefix=lib/shared-ui shared-ui main --squash

Use --squash to keep your project history clean. Without it, the entire library history is merged into your project.

The prefix directory must not already exist. Git will create it and populate it with the library contents.

Pull updates from the shared library

Fetch and merge the latest changes from the shared library into your project's subtree directory.

$ git subtree pull --prefix=lib/shared-ui shared-ui main --squash

Make local changes to the subtree

You can modify subtree files directly in your project and commit them normally. These changes live in your project's history.

$ # Edit files in lib/shared-ui/ as normal git add lib/shared-ui/ git commit -m "fix: correct button hover state in shared-ui"

Push local changes back to the shared library

Extract commits that touched the subtree directory and push them to the shared library repository on a new branch.

$ git subtree push --prefix=lib/shared-ui shared-ui feature/button-fix

Push to a feature branch on the shared library and create a pull request, rather than pushing directly to main.

Split subtree into a standalone branch

Extract the subtree history into a standalone branch. This is useful for initially creating a shared library from code that started in a monorepo.

$ git subtree split --prefix=lib/shared-ui -b shared-ui-standalone

Full Script

full-script.sh

#!/usr/bin/env bash
# git-subtree-manage.sh — Subtree operations helper
set -euo pipefail

ACTION="${1:?Usage: $0 {add|pull|push|split} <prefix> <remote> [branch]}"
PREFIX="${2:?Prefix directory required}"
REMOTE="${3:-}"
BRANCH="${4:-main}"

case "$ACTION" in
  add)
    if [ -z "$REMOTE" ]; then
      echo "Usage: $0 add <prefix> <remote-url> [branch]"
      exit 1
    fi
    REMOTE_NAME=$(basename "$REMOTE" .git)
    echo "Adding remote '$REMOTE_NAME'..."
    git remote add "$REMOTE_NAME" "$REMOTE" 2>/dev/null || echo "Remote already exists."
    git fetch "$REMOTE_NAME"
    echo "Adding subtree at $PREFIX from $REMOTE_NAME/$BRANCH..."
    git subtree add --prefix="$PREFIX" "$REMOTE_NAME" "$BRANCH" --squash
    echo "Done. Shared code is at $PREFIX/"
    ;;
  pull)
    REMOTE_NAME="${REMOTE:?Remote name required}"
    echo "Pulling updates into $PREFIX from $REMOTE_NAME/$BRANCH..."
    git subtree pull --prefix="$PREFIX" "$REMOTE_NAME" "$BRANCH" --squash
    echo "Updated."
    ;;
  push)
    REMOTE_NAME="${REMOTE:?Remote name required}"
    echo "Pushing subtree changes from $PREFIX to $REMOTE_NAME/$BRANCH..."
    git subtree push --prefix="$PREFIX" "$REMOTE_NAME" "$BRANCH"
    echo "Pushed."
    ;;
  split)
    SPLIT_BRANCH="${REMOTE:-${PREFIX//\//-}-standalone}"
    echo "Splitting $PREFIX into branch '$SPLIT_BRANCH'..."
    git subtree split --prefix="$PREFIX" -b "$SPLIT_BRANCH"
    echo "Branch '$SPLIT_BRANCH' created with subtree history."
    ;;
  *)
    echo "Usage: $0 {add|pull|push|split} <prefix> <remote> [branch]"
    exit 1
    ;;
esac

FAQ

Discussion

Loading comments...

#!/usr/bin/env bash # git-subtree-manage.sh — Subtree operations helper set -euo pipefail ACTION="${1:?Usage: $0 {add|pull|push|split} <prefix> <remote> [branch]}" PREFIX="${2:?Prefix directory required}" REMOTE="${3:-}" BRANCH="${4:-main}" case "$ACTION" in add) if [ -z "$REMOTE" ]; then echo "Usage: $0 add <prefix> <remote-url> [branch]" exit 1 fi REMOTE_NAME=$(basename "$REMOTE" .git) echo "Adding remote '$REMOTE_NAME'..." git remote add "$REMOTE_NAME" "$REMOTE" 2>/dev/null || echo "Remote already exists." git fetch "$REMOTE_NAME" echo "Adding subtree at $PREFIX from $REMOTE_NAME/$BRANCH..." git subtree add --prefix="$PREFIX" "$REMOTE_NAME" "$BRANCH" --squash echo "Done. Shared code is at $PREFIX/" ;; pull) REMOTE_NAME="${REMOTE:?Remote name required}" echo "Pulling updates into $PREFIX from $REMOTE_NAME/$BRANCH..." git subtree pull --prefix="$PREFIX" "$REMOTE_NAME" "$BRANCH" --squash echo "Updated." ;; push) REMOTE_NAME="${REMOTE:?Remote name required}" echo "Pushing subtree changes from $PREFIX to $REMOTE_NAME/$BRANCH..." git subtree push --prefix="$PREFIX" "$REMOTE_NAME" "$BRANCH" echo "Pushed." ;; split) SPLIT_BRANCH="${REMOTE:-${PREFIX//\//-}-standalone}" echo "Splitting $PREFIX into branch '$SPLIT_BRANCH'..." git subtree split --prefix="$PREFIX" -b "$SPLIT_BRANCH" echo "Branch '$SPLIT_BRANCH' created with subtree history." ;; *) echo "Usage: $0 {add|pull|push|split} <prefix> <remote> [branch]" exit 1 ;; esac