Subtrees

You can use the Subtrees tab to manage external repositories embedded as subdirectories in your project.

Note

The git subtree command must be available on your system. If the git subtree command is not installed, the tab shows a git subtree not available message.

Navigate the Subtrees tab

To open the Subtrees tab, click Git > Subtrees, or right-click a subtree folder in the File Browser and click Show in Subtrees. The tab belongs to the repository it was opened from, and opening it again brings that tab forward rather than making a second one.

Every Git tool tab carries a Git tools control beside its title. Use it to move between Git Summary, Remotes, Submodules, Subtrees, Git LFS, Sparse Checkout, Repository Config, and Hooks. The menu marks the tool you are on, and choosing a tool opens it for this repository, or brings its tab forward when it is already open. Each tool is its own tab, so two projects can each have their own.

Subtrees are listed alphabetically. Each card shows, on its own line:

• the directory path
• why it cannot be used, when that applies: the state names itself at the head of the line, as in Not configured: found in history, not connected to a remote yet
• where it pulls from, the tracked branch, and whether squash is off

A subtree stores its own upstream address. When exactly one remote in your repository points at that address, the card shows that remote’s name, because a name is friendlier to read than a URL. When no remote does, or when several do, the card shows the address itself. Both are ordinary, and neither changes what Pull and Push do.

A URL shown on a card is always redacted: if you configured the subtree with an address containing a username and token, the card shows the address without them. The full value stays in the Configure dialog’s field, where you can edit it.

A subtree that is not connected yet shows nothing there. Zide may know where the directory came from, from the trailers in your commit history, but a recovered URL is a suggestion rather than an upstream. It appears where you act on it: in the Configure dialog.

The tracked branch is not a link: it names a branch in the subtree’s own upstream repository, which your repository may not have fetched.

To open the commit that last merged the subtree, open the row menu and click Show Last Merge Commit. It is an ordinary commit in your repository and opens like any other. The item is greyed out on a subtree Zide has not detected a merge commit for yet.

Recover a moved subtree folder

A subtree card reports each folder problem at the head of its own line.

• Folder not found: Zide cannot find the subtree at its recorded path. The row offers a primary Locate… button with the tooltip Reconnect this subtree to its current folder. Click it to open Locate subtree folder, then enter or choose the folder’s current project-relative path. Zide moves the subtree settings and saved account binding to that path. It does not move files or create a commit.
• Subtree move needs repair: The folder was moved and committed outside Zide. The row offers a primary Repair… button with the tooltip Make Pull, Push, and Split work at this folder. Click it to open Repair subtree after move?. Zide creates one empty commit that connects the subtree history to the new path. It does not change project files. Pull, Push, and Split… do not run until you repair the move.
• Folder moved: The folder move has not been committed in Zide. Commit the move before you use Pull, Push, or Split….

Add a subtree

To add a subtree, complete the following steps.

1. In the Subtrees tab, click Add Subtree. You can also right-click a folder in the File Browser and choose Create Subtree Here…, which opens the same dialog with that folder already set as the parent.
2. In the Add Subtree dialog, select a repository.
3. Choose where it lands. Parent Folder is a folder inside this repository, and Browse… opens at the repository root; leave it empty to add the subtree at the top level. The line beneath says where it resolves to: Will create in: C:/dev/myrepo/vendor/library.
4. Optional: Advanced Options holds the Folder name override, which replaces the repository name when set, the Branch to track, which defaults to the remote’s, and Squash commits, which is on. All three can be changed later.
5. Click Add Subtree.

Zide records the subtree’s URL, tracked branch, and squash setting when the add succeeds, so Pull and Push do not ask for a URL again.

How Zide remembers a subtree

Unlike submodules, Git subtrees have no .gitmodules file, so a subtree directory carries no record of where it came from.

Zide stores that record in your repository’s local configuration, which is ordinary Git configuration you can inspect and edit outside Zide:

[zide-subtree "vendor/library"]
    url = https://example.com/library.git
    ref = main
    squash = true

This is local repository configuration, so it is shared by every worktree of the repository and is not copied when someone else clones it.

Zide never creates a remote for a subtree. The upstream address belongs to the subtree, so renaming, repointing or deleting any remote cannot change where a subtree pulls from. It can only change whether the card shows a remote’s name or the address itself.

One consequence is worth knowing: because Pull and Push are given the address rather than a remote name, settings that Git attaches to a named remote do not apply. That means remote.<name>.pushurl and extra push destinations, custom fetch refspecs, and a remote-specific Git LFS endpoint (remote.<name>.lfsurl). If your upstream needs one of those, use git subtree directly for that subtree.

Which account a subtree authenticates as

A private upstream needs credentials, and Zide binds them to the subtree itself rather than to a remote. Both the Add Subtree and Configure Subtree dialogs work out which account applies from the URL, and only ask when the URL leaves something to decide:

• While Zide checks an HTTP address, Authentication shows Resolving….
• A local path shows Local source. An SSH address shows System SSH configuration. Neither uses a connected provider account. Other non-HTTP sources show System Git configuration.
• An HTTPS host with one matching connected account shows the account name and provider.
• An HTTPS host with two or more matching accounts shows an Authentication list. A subtree with a saved account binding also shows the list, even when only one account matches. Choose System Git credentials to remove the binding.
• An HTTPS host with no matching account shows System Git credentials. Git uses its configured credential helper.

Editing the branch or squash setting does not change the binding. Editing the URL resolves authentication again. Choosing a repository through Browse… sets the binding, because picking a repository through an account is itself a choice of identity.

Connect an existing subtree

A subtree added outside Zide, or before this record existed, is still listed: Zide finds it by reading git-subtree-dir: trailers in your commit history. Such a row reads Not configured and offers a single Configure… button, because a subtree with no stored upstream has exactly one thing it can do. Pull and Push appear once it is connected.

Note

In a shallow clone, Zide can detect only subtree records present in the available history. Fetch the full history if an expected subtree is not listed.

To connect it, complete the following steps.

1. In the subtree row, click Configure…, or open the row menu and click Configure….
2. In the Configure Subtree dialog, choose the repository. The Repository source field takes any address Git accepts, and Browse… opens repositories from your connected provider accounts. When history contains more than one possible source for an unconfigured subtree, choose one from the history control below the field and click Use source. The field stays typeable, and an address you enter that matches one existing remote, ignoring a trailing slash or .git, inherits that remote’s saved account binding. The Authentication area shows how later pulls and pushes authenticate.
3. Optional: Set the Tracked branch that Pull and Push should use. Click the caret to choose from the branches on the remote, or type a branch name. Leave it blank to use the remote’s default branch.
4. Optional: Clear Squash commits to keep the upstream history of each pull. Squashing does not prevent pushing, but it can make a later push take longer because Git may need to re-derive more of the subtree’s history.
5. Click Save.

Subtree actions

Subtrees listed here are included when you push and pull your project.

For Advanced Users: Use Pull here only to import changes from the subtree’s source repository. Use Push here only to publish changes back to that source. Both use the tracked branch and squash setting stored for that subtree, so neither asks for a URL.

A subtree with affected nested submodules shows This subtree contains submodules. Pushing this subtree is not recommended. on its card. Before Zide pushes, it lists the affected submodules and warns that they will become empty folders and require manual repair on the remote.

To compare the committed subtree changes with its source before choosing one of those operations, open the row menu and click Check Sync Status. This is an on-demand check: Zide does not contact the source or calculate the subtree’s history until you ask. After the check, the Pull button shows how many committed source changes are available to import, and the Push button shows how many committed project changes are available to publish. Uncommitted files are not included in either number. If both numbers are zero, Zide briefly reports that committed changes are up to date. The result is cleared after the subtree or project changes, so an old count is not presented as current.

Only one subtree operation runs in a repository at a time, because two at once fail unpredictably. Start another and its button reads Waiting…; you can queue as many as you like, including a pull and a push on the same subtree. Click a waiting button to call that operation off before it starts.

If a conflict appears while operations are waiting, Zide stops every waiting operation before it reaches Git. Zide reports how many it stopped and tells you to resolve the repository conflicts before you try them again. If Zide cannot verify the repository state, it still stops every waiting operation, reports the count, and tells you to check Staging before you try again.

To stop the operation that is already running, open the row menu and click Cancel. Zide ends the Git process and changes nothing else in your repository: an interrupted operation cannot be told apart from work you started yourself while it ran, so repairing it automatically could discard the wrong thing. Stopping is also not undoing, because a push interrupted partway through does not un-send what the remote already accepted. If the repository is left needing attention, Zide’s usual conflict indicators show it.

Resolve conflicts in Staging

When the repository has an unresolved merge or rebase, a banner across the top reports the unresolved files or the Git operation in progress. When a subtree operation leaves conflicts, the banner identifies that operation and its subtree. Both banners tell you to resolve or abort the operation in Staging and offer Resolve in Staging, which opens Staging.

While either banner is present, Zide disables the row action buttons. Their tooltip says Resolve repository conflicts in Staging first. A row whose subtree operation left the conflicts also shows a Conflict badge beside its path.

Open the row menu and click Split… to turn the subtree directory back into a standalone history.

Adding a subtree merges another project’s files into a subdirectory of yours, and from then on its commits are mixed in with all your others. Split is the reverse: it finds every commit that touched that directory, rewrites them with the directory as the repository root, and puts the result on a new branch. In a repository of 418 commits where 12 touched vendor/library, the new branch has those 12, and its files sit at the top level rather than under vendor/library/.

That branch is a normal local branch, and nothing is pushed. Use it to review exactly what you would send upstream, to hand that work to someone, or to promote a directory you have been growing into a repository of its own. Push does the same extraction internally and then sends the result, so Split is the half of Push you can inspect.

Note

Squashing does not stop you pushing. A squashed subtree’s commits still carry a git-subtree-split: trailer naming the upstream commit they came from, and git subtree grafts the history it builds onto that, so the push is an ordinary fast-forward.

What squashing changes is the size of the job. With no recent point to graft onto, Git re-derives the subtree’s history from further back, so a push can take a minute where another takes seconds. The button reports its progress throughout.

The row menu also holds the less frequent actions. Click Show in File Browser to find the subtree’s directory on disk, or Show in Remotes to see the matching remote beside every other remote in the repository. That item is available only when exactly one remote points where the subtree does. Click Configure… to change where the subtree pulls from and pushes to, which branch it tracks, and whether it squashes. Click Remove to remove the subtree.

Items that name the action alone act on the subtree itself. The ones that name something else, a remote or a commit, go somewhere else.

The File Browser marks subtree directories with their own icon, and right-clicking one offers Show in Subtrees to come back here, highlighting that subtree’s card when it arrives.

Removing a subtree deletes its directory, commits the removal, and clears the stored record and the account bound to it. No remote is touched, because Zide never created one for the subtree.