Name

git-subrepo - Git Submodule Alternative

Synopsis

git subrepo -h    # Help Overview

git subrepo clone <remote-url> [<subdir>]
git subrepo init <subdir>
git subrepo migrate <subdir>|--all [--history=prefixed] [--dry-run]
git subrepo pull <subdir>
git subrepo retarget <subdir>
git subrepo push <subdir>

git subrepo fetch <subdir>
git subrepo branch <subdir>
git subrepo commit <subdir>
git subrepo config <subdir>

git subrepo status [<subdir>]
git subrepo log <subdir> [--group-equivalent] [--incoming] [--fetch]
git subrepo clean <subdir>

git subrepo help [<command> | --all]
git subrepo version
git subrepo upgrade

Description

This git command "clones" an external git repo into a subdirectory of your repo. Later on, upstream changes can be pulled in, and local changes can be pushed back. Simple.

Benefits

This command is an improvement from git-submodule and git-subtree; two other git commands with similar goals, but various problems.

It assumes there are 3 main roles of people interacting with a repo, and attempts to serve them all well:

• owner - The person who authors/owns/maintains a repo.

• users - People who are just using/installing the repo.

• collaborators - People who commit code to the repo and subrepos.

The git-subrepo command benefits these roles in the following ways:

• Simple and intuitive commandline usage (with tab completion).

• Users get your repo and all your subrepos just by cloning your repo.

• Users do not need to install git-subrepo, ever.

• Collaborators do not need to install unless they want to push/pull.

• Collaborators know when a subdir is a subrepo (it has a .gitrepo file).

• The .gitrepo file never gets pushed back to the subrepo upstream.

• Well named branches and remotes are generated for manual operations.

• Owners do not deal with the complications of keeping submodules in sync.

• Independent shared directories can be synchronized separately.

• Parent branches and linked worktrees can use shared repositories.

• Different branches can have different subrepos in different states, etc.

• Nested subrepos and directory moves remain legacy-only features.

• You can init an existing subdirectory into a subrepo.

• New subrepos retain individual imported commits under the shared directory.

• git log --first-parent keeps a compact project-level view.

• Pulls can use a merge, rebase or force strategies.

• You can see the subrepo history with git log subrepo/<subdir>/fetch.

• Commits pushed back upstream are not condensed (by default).

• Trivial to try any subrepo operations and then reset back.

• No configuration required.

• Original upstream commit IDs remain authoritative for synchronization.

• Fixes known rebase failures with git-subtree.

Getting Started with Shared History

New subrepos use prefixed history. Imported commits appear in ordinary Git history with paths inside the shared directory. Existing subrepos keep their old behavior until you explicitly migrate them.

Start from a parent project with at least one commit:

git subrepo clone <remote-url> shared
git subrepo status shared
git subrepo log shared -- --oneline

To update shared files, use git subrepo pull shared. To publish your changes, first commit them normally in the parent project, then run:

git subrepo push shared

Files outside shared/ are not published to the shared remote.

Prefixed-history operations that update the project working tree require no staged or unstaged changes to tracked project files. Untracked and ignored files inside or outside the shared directory can stay in place unless their paths would be overwritten by the prepared update, including file/directory conflicts. Such collisions are refused even with --force; preserve or move the reported files before retrying. Untracked and ignored files are never published. Temporary shared worktrees must still be completely clean before cleanup, including untracked and ignored files, because cleanup removes those worktrees.

Default log output labels local and imported commits. They can represent the same shared change under different IDs. Use git subrepo log shared --group-equivalent to group only entries whose recorded provenance and actual shared changes agree. This does not change Git history. A mixed parent commit can also contain unrelated changes; grouping applies only to its shared portion. Old commits without sufficient provenance are not guessed to be equivalent.

For a compact project view use git log --first-parent. For imported file history use git log -- shared/. Git's normal history simplification and rename handling still apply to path logs and blame.

Migrating an Existing Subrepo

git subrepo fetch shared
git subrepo migrate shared --history=prefixed --dry-run
git subrepo migrate shared --history=prefixed

Migration requires a clean project and shared content matching the recorded upstream commit. It adds one commit, preserves old project commits and content, and upgrades the tracking file. The preview does not fetch or modify anything. Migration does not silently import a newer upstream tip or push your project.

If committed shared content differs from the recorded upstream commit, finish a full subrepo push/pull synchronization first. Pull to integrate incoming changes, resolve and commit conflicts, then push remaining shared changes; pull again if needed to finish synchronization. Fetch alone only downloads history and does not synchronize content or tracking metadata.

Check all subrepos before migrating any:

git subrepo migrate -a --dry-run
git subrepo migrate --all

--all (-a) reports every blocked subrepo. Actual bulk migration checks all subrepos first and changes none if any check fails. Already migrated subrepos are left unchanged. Each legacy subrepo gets its own migration commit. Failures during integration (such as a rejected commit hook) can still leave earlier migrations completed; fix the failure and rerun the command.

Coordinate the transition with collaborators: [subrepo-v2] requires a client that supports prefixed history. Old clients may report a missing subrepo.commit field. Upgrade the client; do not add the old field back. This is an accidental-use guard, not protection against every old forced replacement or manual file edit. The tested upstream 0.4.9 client can return success from status even while reporting missing old settings. Do not use an old client's exit status as a format-compatibility check.

Use --history=legacy when creating a new subrepo that must keep the old format. Recloning an existing subrepo does not silently change its format.

When History Needs Repair

A squash merge, rebase, or cherry-pick may copy tracking settings without their original history links. Before a later pull, push, branch, commit, or retarget, git-subrepo checks those links and explains any required repair.

The repair adds a commit, keeps shared content and other project files unchanged, updates tracking metadata, and restores imported history. Local changes whose original commit boundaries cannot be recovered may be kept as one explicitly labelled change. Read the proposal before approving; approval defaults to No. After approval the requested command continues, including sending changes upstream if you requested a push.

Scripts stop instead of waiting for input. The diagnostic prints a copyable command with --accept-repair=<token>, authorizing only the exact proposed repair. A changed project or request requires a new approval. --force is not approval. Supported repair does not require choosing commit IDs or editing .gitrepo. For --all, repair each affected shared directory using its individual command first. Each repair needs its own approval; then retry the --all operation.

If the upstream itself was force-pushed, required original objects are missing, or tracking settings are ambiguous, repair stops rather than guessing. Preserve your files and check the remote/history with the repository maintainer.

Conflicts, Offline Use, and Worktrees

A conflicting pull leaves an upstream-layout worktree and prints its exact path. Edit the conflicted files there, stage them, finish the merge or rebase, return to your parent project, and run git subrepo commit shared. Follow the printed commands rather than editing the parent's unchanged copy of the files.

For a retarget conflict, finish the merge or rebase in the same way, but rerun the original git subrepo retarget command with its remote and branch overrides instead of commit. The printed retry command preserves those settings.

An ordinary fresh clone retains imported browsing history and provenance. Original upstream objects and cache refs are not necessarily present; fetch before synchronizing when requested. Complete upstream ancestry is required for rewriting or migration; shallow history is not silently treated as complete history.

Operations sharing a parent repository are serialized across its linked worktrees. Offline status, history browsing, and previews participate too. Read- only commands use temporary coordination files, without changing repository objects, refs, or indexes. Detailed status and grouped history compute derived trees and commits in a temporary object directory that is removed when the operation finishes. A busy message refuses the competing operation. Finish the active operation before retrying rather than deleting its worktree. Unfinished shared-worktree edits are preserved. After abrupt termination, retry the same command. The client can reclaim its recorded lock after verifying that the same- machine owner has exited, Git has released its index lock, and its Git child processes have finished. An inherited file descriptor tracks those processes even if the operation shell is killed. Normal cleanup also waits for them before releasing the lock. It then checks the saved update before continuing. If a Git operation is still active, it refuses to take over. An incomplete or unverifiable process lock is preserved for maintainer inspection. This includes interrupted older-client locks without an EOF receipt, or a lost lifetime observer. Hooks and transport wrappers must preserve inherited file descriptor 19 while doing operation-related work; deliberately detached work that closes it is not tracked. This coordination does not prevent unrelated Git commands or older clients from changing the repository; do not run those concurrently with shared operations.

If a push succeeds remotely but a local hook or signature fails, the diagnostic distinguishes those outcomes. Fix the local failure and retry the same push; the pending record lets git-subrepo finish without publishing the changes twice. Interrupted local integrations also retain a retry record. Retry on the same project branch; differing staged or tracked working-file edits are preserved rather than overwritten. Non-conflicting untracked and ignored files can stay in place; colliding paths are refused. Fix the reported hook or signing failure before retrying. If the editor or a later hook or signing step fails, the attempted commit message is saved before rollback. Retrying with --edit reopens that saved draft rather than the original message; edits made by hooks are retained too. Retrying an interrupted --all integration continues the remaining directories without repeating the integrations already completed in that request. Retarget keeps its completed import recorded until publication finishes, so an exact retry does not import the same changes twice. New incoming changes still need integration. If the parent or shared worktree has changed since interruption, the retry preserves that work and stops rather than discarding it.

Recovery files and saved messages are bound to prepared Git blobs under worktree-specific refs. Missing or altered records are refused before checkout or commit, including a missing journal whose prepared-operation ref remains. Attempted commit messages are saved through unique temporary files before replacing the saved message. Pending publications must match the shared snapshot and its reconstructed export before pushing. Preserve the recovery files and refs together; older records without this binding require maintainer inspection. These integrity checks are not authentication against someone who can also replace Git objects, refs, or hooks. Restrict write access to Git administration directories.

Tracking and Signatures

The complete [subrepo-v2] section records metadata format 2, rewrite format 1, the shared path, original upstream ID, imported ID, and synchronization state. Newly initialized directories remain unpublished until their first push; no upstream ID is invented. Managed history fields cannot be changed with config --force.

Both tracking layouts require regular .gitrepo files and real directory components, not symbolic links. Recorded commit IDs must be full hexadecimal object IDs when present. Remotes must be nonempty and cannot begin with -. The upstream setting accepts a plain branch or tag name, or an explicit refs/tags/<tag> selector, not an option, other full ref name, wildcard, or destination-bearing refspec. Fetching does not update unrelated local or remote-tracking refs. Recovery commands quote their arguments; preserve that quoting when copying them into a shell.

Upstream operations resolve plain names against advertised branches and tags. A name matching both is refused; use an unambiguous name or an explicit tag selector. The selected full ref is retained throughout each operation, including repeated fetches, comparisons, and publication; a concurrent namespace change cannot redirect that operation from a branch to a tag or vice versa.

Synchronization permits standard file, Git, HTTP(S), FTP(S), and SSH transports only. External transport helpers are refused even if enabled in Git configuration, including through named remotes, URL rewrites, or push URLs. Git protocol policies and stricter GIT_ALLOW_PROTOCOL restrictions remain enforced.

Shared worktree ownership records follow the same filesystem rules. Detached shared worktrees must have an active rebase identifying the expected branch.

Rewriting preserves author/committer fields and message bytes but changes commit IDs. Original signatures and merge-tag signatures are removed from rewritten objects, which are unsigned. Original upstream objects can be verified separately when available. Parent integration commits use normal Git hooks and configured signing, including when an interrupted integration is retried. Hooks receive the same command environment markers on retries as on ordinary operations. Newly exported commits may contain source- provenance headers; these are not cryptographic proof and do not publish parent-only files.

Directory moves, nested prefixed subrepos, and automatic divergent-upstream recovery are not supported in this format. Do not change the recorded prefix or rewrite format to bypass these restrictions.

Installation

The best short answer is:

git clone https://github.com/ingydotnet/git-subrepo /path/to/git-subrepo
echo 'source /path/to/git-subrepo/.rc' >> ~/.bashrc

The complete "Installation Instructions" can be found below.

Note: git-subrepo requires Git 2.23 or newer and Bash 4.0 or newer.

Commands

All the subrepo commands use names of actual Git commands and try to do operations that are similar to their Git counterparts. They also attempt to give similar output in an attempt to make the subrepo usage intuitive to experienced Git users.

Please note that the commands are not exact equivalents, and do not take all the same arguments. Keep reading�

git subrepo clone <repository> [<subdir>] [-b <branch>] [-f] [-m <msg>] [--file=<msg file>] [-e] [--method <merge|rebase>] [--history=prefixed|legacy]

Add a repository as a subrepo in a subdir of your repository.

This is similar in feel to git clone. You just specify the remote repo url, and optionally a sub-directory and/or branch name. The repo will be fetched and merged into the subdir.

New subrepos default to prefixed history: one project integration commit attaches individual imported commits beneath the shared path. Tracking information is stored in <subdir>/.gitrepo. Use --history=legacy to keep the old condensed history and metadata layout.

All subsequent commands refer to the subrepo by the name of the subdir. From the subdir, all the current information about the subrepo can be obtained.

The --force option will "reclone" (completely replace) an existing subdir. For prefixed history, the repository must match the recorded remote, and an explicit branch must match the recorded branch. Use git subrepo retarget with --remote or --branch to select a different source.

The --method option will decide how the join process between branches are performed. The default option is merge.

The clone command accepts the --branch= --edit, --file, --force and --message= options.

git subrepo init <subdir> [-r <remote>] [-b <branch>] [--method <merge|rebase>] [--history=prefixed|legacy]

Turn an existing subdirectory into a subrepo.

If you want to expose a subdirectory of your project as a published subrepo, this command will do that. It will split out the content of a normal subdirectory into a branch and start tracking it as a subrepo. Afterwards your original repo will look exactly the same except that there will be a <<subdir/.gitrepo >> file.

If you specify the --remote (and optionally the --branch) option, the values will be added to the <subdir>/.gitrepo file. The --remote option is the upstream URL, and the --branch option is the upstream branch to push to. These values will be needed to do a git subrepo push command, but they can be provided later on the push command (and saved to <<subdir/.gitrepo >> if you also specify the --update option).

Note: You will need to create the empty upstream repo and push to it on your own, using git subrepo push <subdir>.

The --method option will decide how the join process between branches are performed. The default option is merge.

The init command accepts the --branch= and --remote= options.

git subrepo migrate <subdir>|--all [--history=prefixed] [--dry-run]

Upgrade an existing legacy subrepo without rewriting published project commits. First synchronize its shared contents and ensure the project is clean. Fetch its recorded upstream history if it is not available locally.

Committed shared changes or a stale synchronization record require a full subrepo push/pull synchronization before migration, not just a fetch. Pull incoming changes, resolve and commit conflicts, then push remaining shared changes and pull again if needed to finish synchronization.

--dry-run explains the change without fetching, creating objects, or modifying project files, refs, or tracking metadata. Migration attaches history from the recorded upstream commit, not necessarily the remote's latest tip. Previews also check rewrite eligibility, including incomplete history, replacement refs, and unsupported nested metadata.

Use --all (-a) to check or migrate every subrepo. The preview reports every blocked subrepo. Actual bulk migration checks all subrepos before changing any; failed checks prevent all migrations. Already migrated subrepos are unchanged. Integration failures can leave earlier migrations completed; rerun after fixing the failure.

Collaborators need a compatible client after receiving the migration commit. Repeating a completed migration is a no-op. Removing already published imported history or changing the rewrite format is not supported.

git subrepo log <subdir> [--incoming] [--fetch] [--group-equivalent] [--oneline] [-- <git-log-options>]

Browse local and imported shared changes without contacting a remote by default. Entries distinguish project-local commits from imported copies and show usable original upstream IDs. A fresh ordinary clone can browse imported history without special subrepo refs.

--incoming shows fetched upstream changes not yet imported. --fetch explicitly refreshes them. Divergent upstream history is not presented as a linear update.

--group-equivalent groups only proven shared-change equivalents using export provenance and actual changes. Missing or unverifiable records stay separate. This can group a verified aggregate squash without treating all its source commits as individually identical to the squash.

For a quick, bounded view:

git subrepo log shared --oneline --group-equivalent -- -5

Count limits (-5, -n 5, or --max-count=5) work with labelled output and grouping. The limit selects commits before grouping; equivalent entries are grouped only when all members are selected, so fewer than five groups may appear. No history is silently hidden when no limit is supplied.

Put other Git log options after --. Those options delegate to Git's output, without subrepo labels, and cannot be combined with grouping. Top-level --oneline still applies; an explicit Git format can override it. Browsing works even with unfinished files in a shared worktree. --fetch updates fetched objects and refs but leaves that worktree untouched. This command does not repair or modify project history.

git subrepo pull <subdir>|--all [-M|-R|-f] [-m <msg>] [--file=<msg file>] [-e] [-b <branch>] [-r <remote>] [-u]

Update the subrepo subdir with the latest upstream changes.

The pull command fetches the latest content from the remote branch pointed to by the subrepo's .gitrepo file, and then tries to merge the changes into the corresponding subdir. It does this by making a branch of the local commits to the subdir and then merging or rebasing (see below) it with the fetched upstream content. After the merge, the content of the new branch replaces your subdir, the .gitrepo file is updated and a single 'pull' commit is added to your mainline history.

The pull command will attempt to do the following commands in one go:

git subrepo fetch <subdir>
git subrepo branch <subdir>
git merge/rebase subrepo/<subdir>/fetch subrepo/<subdir>
git subrepo commit <subdir>
# Only needed for a consequential push:
git update-ref refs/subrepo/<subdir>/pull subrepo/<subdir>

In other words, you could do all the above commands yourself, for the same effect. If any of the commands fail, subrepo will stop and tell you to finish this by hand. Generally a failure would be in the merge or rebase part, where conflicts can happen. Since Git has lots of ways to resolve conflicts to your personal tastes, the subrepo command defers to letting you do this by hand.

When pulling new data, the method selected in clone/init is used. This has no effect on the final result of the pull, since it becomes a single commit. But it does affect the resulting subrepo/<subdir> branch, which is often used for a subrepo push command. See 'push' below for more information. If you want to change the method you can use the config command for this.

When you pull you can assume a fast-forward strategy (default) or you can specify a --rebase, --merge or --force strategy. The latter is the same as a clone --force operation, using the current remote and branch.

In prefixed history, the pull commit attaches the individual incoming commits. Legacy subrepos still condense the incoming changes into one project commit. The original fetched upstream history remains available with:

git log refs/subrepo/<subdir>/fetch

The set of commands used above are described in detail below.

The pull command accepts the --all, --branch=, --edit, --file, --force, --message=, --remote= and --update options.

git subrepo retarget (<subdir> [-b <branch>]|--all) [-r <remote>] [-u] [-f] [--dry-run]

Move a shared folder to a different upstream branch or remote. This command can merge shared files, create commits in this project, and publish committed shared changes to the destination branch. It does not push the project branch.

To retarget all shared folders while keeping their individual branch names:

git subrepo retarget --all [-r <remote>] [-u] [-f] [--dry-run]

--branch cannot be combined with --all. Retarget each shared folder individually to change its branch.

In prefixed history, the new upstream must contain the recorded original upstream history. Divergent replacement is refused. A new branch can be created from the recorded shared history. Tracking settings are committed automatically; do not manually edit or commit tracking IDs.

Preview prefixed retarget with --dry-run. It checks the destination remote and shows the old/new mapping, locally available incoming history, shared-file differences, and any existing worktree. It never fetches objects, changes refs, commits, or publishes. If destination objects are missing, incoming differences are explicitly unknown. The preview does not simulate a merge.

A stale, untouched shared worktree is refreshed from current project changes. Worktree-only commits and completed conflict resolutions are preserved. If both copies have changed, retarget stops and names both locations. Preserve the worktree commits on a separate branch and reconcile the copies before retrying; do not delete unknown work or use force to bypass this check. An identical, completed retarget makes no new commit.

If conflicts occur, resolve and finish the merge or rebase in the printed worktree, then rerun the original retarget command with the same remote and branch options. Do not substitute a normal subrepo commit.

In legacy history only, retarget also supports an upstream without the old shared history. It creates or reuses the shared branch, merges the new upstream and pushes it. Commit its changed .gitrepo settings before the next pull. Legacy retarget does not support --dry-run.

Legacy retarget to a tag requires --force before changing files or refs. The tag update uses a lease on the fetched tag object, so a concurrent tag change is refused. Retarget to a branch still never force-pushes.

Use --branch and/or --remote to override the upstream. Retarget persists those overrides by default; --update may also be supplied explicitly. The command accepts --all, --branch=, --remote=, --update, --force, and (for prefixed history) --dry-run.

git subrepo push <subdir>|--all [<branch>] [-m msg] [--file=<msg file>] [-r <remote>] [-b <branch>] [-M|-R] [-u] [-f] [-s]

Push a properly merged subrepo branch back upstream.

This command takes the subrepo branch from a successful pull command and pushes the history back to its designated remote and branch. You can also use the branch command and merge things yourself before pushing if you want to (although that is probably a rare use case).

The push command requires a branch that has been properly merged/rebased with the upstream HEAD (unless the upstream HEAD is empty, which is common when doing a first push after an init). That means the upstream HEAD is one of the commits in the branch.

By default the branch ref refs/subrepo/<subdir>/pull will be pushed, but you can specify a (properly merged) branch to push.

After that, the push command just checks that the branch contains the upstream HEAD and then pushes it upstream.

If the subdir content is already identical to the upstream commit recorded in <subdir>/.gitrepo (the .gitrepo file itself is never compared, since it does not exist upstream), then there is nothing to contribute and push reports that it has no new commits. It does not reconstruct the local history in that case, and it records the sync point in <subdir>/.gitrepo so that later push and status commands do not have to consider the same range again.

This means local subrepo commits whose net effect on the content is nothing new to upstream are not pushed. To send such history upstream deliberately, reconstruct it with git subrepo branch <subdir> and push that branch explicitly with git subrepo push <subdir> subrepo/<subdir>.

In legacy mode, the --force option will do a force push. Force pushes are typically discouraged. Only use this option if you fully understand it. (The --force option will NOT check for a proper merge. ANY branch will be force pushed!) Prefixed history refuses force pushes, including under --all. Pull and resolve incoming changes first, or use retarget for a supported upstream transition.

A subrepo push sends shared-directory files, not project-only files. Exported commit messages retain the original message, which may mention both kinds of files. Publish the project's new tracking commits separately with git push when ready. Imported shared commits can make Git's project ahead-count large; that count is not the number of unpublished shared edits. Use subrepo status for folder-level actions and git log --first-parent --oneline for project integration history.

In prefixed mode, --update records changed remote or branch settings even when there are no shared files to publish. This creates a project bookkeeping commit, not a remote push. Repeating already recorded settings makes no new commit.

The push command accepts the --all, --branch=, --file, --force, --merge, --message, --rebase, --remote=, --squash and --update options.

git subrepo fetch <subdir>|--force --all [-r <remote>] [-b <branch>]

Fetch the remote/upstream content for a subrepo.

It will create a Git reference called subrepo/<subdir>/fetch that points at the same commit as FETCH_HEAD. It will also create a remote called subrepo/<subdir>. These are temporary and you can easily remove them with the subrepo clean command.

The fetch command accepts the --force, --all, --branch= and --remote= options.

git subrepo branch <subdir>|--all [-f] [-F]

Create a branch with local subrepo commits.

Scan the history of the mainline for all the commits that affect the subdir and create a new branch from them called subrepo/<subdir>.

This is useful for doing pull and push commands by hand.

Use the --force option to write over an existing subrepo/<subdir> branch.

The branch command accepts the --all, --fetch and --force options.

git subrepo commit <subdir> [<subrepo-ref>] [-m <msg>] [--file=<msg file>] [-e] [-f] [-F]

Add subrepo branch to current history as a single commit.

This command is generally used after a hand-merge. You have done a subrepobranch and merged (rebased) it with the upstream. This command takes the HEAD of that branch, puts its content into the subrepo subdir and adds a new commit for it to the top of your mainline history.

This command requires that the upstream HEAD be in the subrepo/<subdir> branch history. That way the same branch can push upstream. Use the --force option to commit anyway.

The commit command accepts the --edit, --fetch, --file, --force and --message= options.

git subrepo status [<subdir>|--all|--ALL] [-F] [-q|-v]

Get the status of a subrepo. Uses the --all option by default. If the --quiet flag is used, just print the subrepo names, one per line.

The --verbose option will show all the recent local and upstream commits. In prefixed mode it also shows the original and imported tracking IDs. Ordinary status is offline: it explicitly says the remote was not checked, and incoming information is cached. Use --fetch to check the remote now. A later remote update still requires another fetch; status does not continuously synchronize projects.

Use --ALL to show the subrepos of the subrepos (ie the "subsubrepos"), if any.

The status command accepts the --all, --ALL, --fetch, --quiet and --verbose options.

git subrepo clean <subdir>|--all|--ALL [-f]

Remove artifacts created by fetch and branch commands.

The fetch and branch operations (and other commands that call them) create temporary things like refs, branches and remotes. This command removes all those things.

Use --force to remove refs. Refs are not removed by default because they are sometimes needed between commands.

Use --all to clean up after all the current subrepos. Sometimes you might change to a branch where a subrepo doesn't exist, and then --all won't find it. Use --ALL to remove any artifacts that were ever created by subrepo.

To remove ALL subrepo artifacts:

git subrepo clean --ALL --force

The clean command accepts the --all, --ALL, and --force options.

git subrepo config <subdir> <option> [<value>] [-f]

Read or update configuration values in the subdir/.gitrepo file.

Because most of the values stored in the .gitrepo file are generated you will need to use --force if you want to change anything else then the method option.

Example to update the method option for a subrepo:

git subrepo config foo method rebase

git subrepo help [<command>|--all]

Same as git help subrepo. Will launch the manpage. For the shorter usage, use git subrepo -h.

Use git subrepo help <command> to get help for a specific command. Use --all to get a summary of all commands.

The help command accepts the --all option.

git subrepo version [-q|-v]

This command will display version information about git-subrepo and its environment. For just the version number, use git subrepo --version. Use --verbose for more version info, and --quiet for less.

The version command accepts the --quiet and --verbose options.

git subrepo upgrade

Upgrade the git-subrepo software itself. This simply does a git pull on the git repository that the code is running from. It only works if you are on the master branch. It won't work if you installed git-subrepo using make install; in that case you'll need to make install from the latest code.

Command Options

-h

Show a brief view of the commands and options.

--help

Gives an overview of the help options available for the subrepo command.

--version

Print the git-subrepo version. Just the version number. Try the version command for more version info.

--all (-a)

If you have multiple subrepos, issue the command to all of them (if applicable).

--ALL (-A)

If you have subrepos that also have subrepos themselves, issue the command to ALL of them. Note that the --ALL option only works for a subset of the commands that --all works for.

--branch=<branch-name> (-b <branch-name>)

Use a different upstream branch-name than the remote HEAD or the one saved in .gitrepo locally.

--dry-run

Preview migration or prefixed retarget without changing files, refs, or history. Migration is offline; retarget checks the destination with the remote but does not fetch or publish. This option is not supported by push.

--edit (-e)

Edit the commit message before committing.

--fetch (-F)

Use this option to fetch the upstream commits, before running the command.

--file=<commit msg file>

Supply your own commit message from a file

--force (-f)

Use this option to force certain commands that fail in the general case.

NOTE: The --force option means different things for different commands. Read the command specific doc for the exact meaning.

--merge (-M)

Use a merge strategy to include upstream subrepo commits on a pull (or setup for push).

--message=<message> (-m <message>)

Specify your own commit message on the command line.

--rebase (-R)

Use a rebase strategy to include upstream subrepo commits on a pull (or setup for push).

--remote=<remote-url> (-r <remote-url>)

Use a different remote-url than the one saved in .gitrepo locally.

--squash (-s)

Squash all commits on a push into one new commit.

--update (-u)

If --branch or --remote are used, and the command updates the .gitrepo file, include these values to the update.

Output Options

--quiet (-q)

Print as little info as possible. Applicable to most commands.

--verbose (-v)

Print more information about the command execution and results. Applicable to most commands.

--debug (-d)

Show the actual git (and other) commands being executed under the hood. Applicable to most commands.

--DEBUG (-x)

Use the Bash set -x option which prints every command before it is run. VERY noisy, but extremely useful in deep debugging. Applicable to all commands.

Environment Variables

The git-subrepo command exports and honors some environment variables:

GIT_SUBREPO_ROOT

This is set by the .rc file, if you use that method to install / enable git-subrepo. It contains the path of the git-subrepo repository.

GIT_SUBREPO_RUNNING

This variable is exported when git-subrepo is running. It is set to the pid of the git-subrepo process that is running. Other processes, like git hooks for instance, can use this information to adjust accordingly.

GIT_SUBREPO_COMMAND

This variable is exported when git-subrepo is running. It is set to the name of the git-subrepo subcommand that is running.

GIT_SUBREPO_PAGER

Use this to specify the pager to use for long output commands. Defaults to $PAGER or less.

GIT_SUBREPO_QUIET

Set this for quiet (-q) output.

GIT_SUBREPO_VERBOSE

Set this for verbose (-v) output.

GIT_SUBREPO_DEBUG

Set this for debugging (-d) output.

Installation Instructions

There are currently 3 ways to install git-subrepo. For all of them you need to get the source code from GitHub:

git clone https://github.com/ingydotnet/git-subrepo /path/to/git-subrepo

The first installation method is preferred: source the .rc file. Just add a line like this one to your shell startup script:

source /path/to/git-subrepo/.rc

That will modify your PATH and MANPATH, and also enable command completion.

The second method is to do these things by hand. This might afford you more control of your shell environment. Simply add the lib and man directories to your PATH and MANPATH:

export GIT_SUBREPO_ROOT="/path/to/git-subrepo"
export PATH="/path/to/git-subrepo/lib:$PATH"
export MANPATH="/path/to/git-subrepo/man:$MANPATH"

See below for info on how to turn on Command Completion.

The third method is a standard system install, which puts git-subrepo next to your other git commands:

make install        # Possibly with 'sudo'

This method does not account for upgrading and command completion yet.

Windows

This command is known to work in these Windows environments:

• Git for Windows -- https://git-for-windows.github.io/

• Babun -- http://babun.github.io/

• Cygwin -- https://www.cygwin.com/

Let us know if there are others that it works (or doesn't work) in.

Testing

The test harness isolates HOME, XDG configuration, and global/system Git configuration on every supported Git version. It does not disable TLS certificate verification or change the developer's real Git configuration.

The git-subrepo repository comes with a extensive test suite. You can run it with:

make test

Test files run in four parallel jobs, each with its own temporary repositories and Git configuration. Use make test jobs=1 to run serially, or set jobs to another positive number to adjust concurrency. The same setting applies to Docker test targets. make CI_TEST keeps the oldest Bash/Git combination serial because old Git can stall under emulated parallel execution; the newest uses jobs. Override the oldest separately with make CI_TEST legacy_jobs=2.

For per-file timings or a focused test:

make test prove=--timer
make test test=test/history-rebase-resolution.t

Without make on your system:

prove -j4 -v test

Upgrading

If you used the .rc or PATH method of installation, just run this to upgrade git-subrepo:

git subrepo upgrade

Or (same thing):

cd /path/to/git-subrepo
git pull

If you used make install method, then run this again (after git pull):

make install        # Possibly with 'sudo'

Command Completion

The git subrepo command supports <TAB>-based command completion. If you don't use the .rc script (see Installation, above), you'll need to enable this manually to use it.

In Bash

If your Bash setup does not already provide command completion for Git, you'll need to enable that first:

source <Git completion script>

On your system, the Git completion script might be found at any of the following locations (or somewhere else that we don't know about):

• /etc/bash_completion.d/git

• /usr/share/bash-completion/git

• /usr/share/bash-completion/completions/git

• /opt/local/share/bash-completion/completions/git

• /usr/local/etc/bash_completion.d/git

• ~/.homebrew/etc/bash_completion.d/git

In case you can't find any of these, this repository contains a copy of the Git completion script:

source /path/to/git-subrepo/share/git-completion.bash

Once Git completion is enabled (whether you needed to do that manually or not), you can turn on git-subrepo completion with a command like this:

source /path/to/git-subrepo/share/completion.bash

In zsh

In the Z shell (zsh), you can manually enable git-subrepo completion by adding the following line to your ~/.zshrc, before the compinit function is called:

fpath=('/path/to/git-subrepo/share/zsh-completion' $fpath)

Status

The git-subrepo command has been used in production and seems to get the job done. Development is still ongoing but mostly just for fixing bugs.

Trying subrepo out is simple and painless (this is not git submodule). Nothing is permanent (if you do not push to shared remotes). ie You can always play around and reset back to the beginning without pain.

This command has a test suite (run make test), but surely has many bugs. If you have expertise with Git and subcommands, please review the code, and file issues on anything that seems wrong.

If you want to chat about the git-subrepo command, join #gitcommands on irc.freenode.net.

Notes

• Works on POSIX systems: Linux, BSD, OSX, etc.

• Works on various Windows environments. See "Windows" section above.

• The git-subrepo repo itself has 2 subrepos under the ext/ subdirectory.

• Written in (very modern) Bash, with full test suite. Take a look.

• A .gitrepo file never is in the top level dir (next to a .git/ dir).

Working with nested subrepos

This workflow applies only to legacy history. Explicitly select --history=legacy when cloning or initializing subrepos for this workflow. Prefixed history is the default and rejects nested tracking metadata, including metadata in earlier upstream commits. These nested repositories cannot currently be migrated to prefixed history.

Legacy history supports adding subrepos which themselves make use of subrepos. In fact, subrepo itself is built this way. Take a look in the ext/ folder, it houses 2 dependencies as subrepos, test-more-bash and bashplus.

test-more-bash itself depends on 2 more subrepos: bashplus again, and test-tap-bash.

The structure is therefore as follows:

git-subrepo
  |- bashplus
  |- test-more-bash
    |- bashplus
    |- test-tap-bash

However, it's important to understand how this works. Here's the key idea: There is no special handling for nested subrepos in legacy mode.

When you clone a subrepo with --history=legacy, all git-subrepo does is download the code and set up the subrepo file. The legacy subrepo commands simply act on the subrepo as a whole, treating nested subrepos like any other part of the source code.

Let's look at what this means in practice. Say you have a structure as follows:

app-foo
  |- barlib
     |- bazlib

You're working on app-foo, and make some changes to bazlib. How should you upstream these changes?

From the perspective of app-foo, you've simply made some changes to barlib. Whether or not those changes were themselves in a subrepo is irrelevant. So, just like any other changes, you run

git subrepo push barlib

Now, if barlib is a library you don't maintain, your responsibility would end here. barlib's maintainer would see your changes and decide what to do with them.

If you do maintain barlib, you might now want to upstream the changes all the way into bazlib. You could be tempted to try running something like:

git subrepo push barlib/bazlib

but you'll soon find out that doesn't work. app-foo doesn't know anything about the link between barlib and bazlib.

What you should do is treat the changes to barlib as if they would come from another contributor, aka:

• go to a local copy of barlib

• pull down the changes with git pull

• you notice the changes include some work on your subrepo, time to upstream them: git subrepo push bazlib

And you're done! One final step you'll likely want to do is to go back to app-foo and run git subrepo pull barlib, because the push you just did added a new commit.

Authors

• Ingy döt Net <ingy@ingy.net>

• Magnus Carlsson <grimmymail@gmail.com>

• Austin Morgan <admorgan@morgancomputers.net>

License and Copyright

The MIT License (MIT)

Copyright (c) 2013-2024 Ingy döt Net