Sparse Checkout
You can use the Sparse Checkout tab to control which repository directories are present in your working tree.
Navigate the Sparse Checkout tab
To open the Sparse Checkout tab, click Git > Sparse Checkout. If the repository uses sparse checkout, you can also select the Sparse checkout row above the file browser tree. See Sparse checkout status. The tab stays with its repository. Opening it again brings the existing tab forward.
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.
What sparse checkout does
Sparse checkout controls which files Git places in your working tree. Nothing is removed from the repository: files outside your selection stay in history and come back the moment you include their directory again.
Sparse checkout can save disk space and reduce file-scanning time in a large repository. Use it when you need only part of the repository’s files.
Enable sparse checkout
When sparse checkout is disabled, the Included Directories section says that all repository files are checked out.
To enable sparse checkout, complete the following steps.
- Click Enable Sparse Checkout.
- Clear the directories that you do not need in the working tree. Root-level files stay in the working tree.
- Click Continue.
- In the Enable Sparse Checkout? confirmation, check the Directories to keep list.
- Click Enable.
The dialog starts with all top-level directories selected, because all of them are in the working tree. To keep part of a directory, clear the directory, expand it, and select the subdirectories to keep.
Zide applies the selection only after you click Enable. Click Back to change the selection. To cancel, click Cancel in the directory picker. The picker is the same one that Add Directories uses.
Continue is unavailable until the repository directories load and you clear at least one directory.
To keep only root-level files, clear all directories and click Continue. In the Keep Only Root-Level Files? confirmation, click Enable.
Clean tracked files outside the selection disappear from this working tree. The repository contents and Git history are unchanged.
If sparse checkout is enabled elsewhere while the dialog is open, Zide shows an error and the existing selection. It does not replace that selection.
Read the included selection
Each selected directory includes all its files and subdirectories. The tree under Included Directories lists your selections, rather than every included folder.
An ancestor marked path only shows a selected directory’s location. It does
not include neighboring directories. For example, selecting services/api does
not include services/web.
When no directories are selected, only root-level files are checked out.
Git calls this way of selecting directories cone mode. Zide also uses this term in the pattern panel described in Switch from patterns to a directory selection.
Exclude a directory
Click Exclude beside an included directory to take that exact directory out of the working tree.
Zide asks you to confirm, and names the directory. Confirming has these effects.
- Clean tracked files inside the directory disappear from this working tree.
- The repository contents and Git history are unchanged.
- You can include the directory again at any time.
After the exclusion, focus moves to the next Exclude button, or to the previous one when you excluded the last directory in the tree, or to Add Directories when nothing is left to exclude.
When you exclude the last included directory, only root-level files remain checked out.
Add directories
To add directories, complete the following steps.
- Click Add Directories.
- In the Add Directories dialog, select the directories to include in the working tree.
- Click Add Selected (N), where N is the number of directories that will be added.
The picker first shows the repository’s top-level directories. Click a directory’s arrow to show its subdirectories. Directories without subdirectories have no arrow.
The checkboxes show how each row relates to your selection.
| Row state | Meaning |
|---|---|
| Included | The current sparse checkout already covers this directory, either directly or through an included ancestor. The checkbox is selected and locked. |
| Selected by parent | You selected an ancestor in this dialog. The checkbox is selected and locked because the parent already covers this directory. |
| Partial checkbox | The row has an included or newly selected descendant. The parent itself is not selected. |
Selecting a directory includes all its subdirectories. If you select both a directory and one of its subdirectories, only the parent counts in Add Selected (N).
Press Escape to close the picker without adding directories.
Move around the picker with the keyboard
The picker is a tree. Tab moves into it and out of it as a single stop rather than visiting every row.
| Key | Action |
|---|---|
| Up and Down | Move between the visible rows. |
| Right | Expand the focused directory, or move into it when it is already expanded. |
| Left | Collapse the focused directory, or move to its parent when it is already collapsed. |
| Home and End | Move to the first or last visible row. |
| Space | Select or clear the focused directory. |
| Enter | Expand or collapse the focused directory. |
When a directory covers selections you already have
Selecting a parent of a directory you already include replaces those child selections with the parent. The picker shows this as you do it: the moment you tick the parent, each covered child locks and reads Included or Selected by parent.
After you add it, the parent is the only row left for that branch. Its children are still in your working tree, included through the parent, which is what the line under the heading says.
When directories cannot be loaded
A failed load stays where it happened and offers Retry.
- If the repository’s top-level directories cannot be read, the picker shows the failure in place of the tree.
- If one directory’s subdirectories cannot be read, the failure appears beneath that row and the row stays collapsed. A row is never shown as expanded when its contents could not be loaded.
Switch from patterns to a directory selection
A worktree whose sparse checkout is defined by a hand-written pattern file shows Sparse Checkout Patterns and the Pattern Mode badge. The tab shows the exact pattern file contents as read-only text. Zide can show these patterns but cannot edit them.
Switching to a directory selection lets you pick folders from a list and lets Zide include and exclude them. Git calls that cone mode.
Click Copy Patterns first if you want to keep a copy of the pattern file. Zide cannot restore it afterwards.
To switch, complete the following steps.
- Click Switch to Directory Selection….
- In the Switch to Directory Selection dialog, choose the directories to keep in your working tree. This dialog uses the same hierarchical picker as Add Directories.
- Click Continue.
- In the Replace Sparse Checkout Patterns? confirmation, click Replace.
The directories you chose replace the pattern file. Zide cannot restore the old patterns after you confirm.
When sparse checkout needs attention
The tab shows Sparse checkout needs attention when the worktree has an incomplete or unreadable sparse-checkout configuration. This includes a configuration or mode setting that cannot be read, a missing or unreadable definition file, a pattern file that is not valid UTF-8, or a cone-mode directory list that Git cannot read or returns in an invalid form.
Click Check Again after you correct the configuration outside Zide. Open Technical details to see the diagnostic information.
| Row | What it shows |
|---|---|
| Code | The diagnostic code for the problem. |
| Mode setting | Cone or Pattern. |
| Definition file | Present or Missing. |
The disclosure also shows the diagnostic detail when one is available.
You can leave this state by disabling sparse checkout. Click Disable Sparse Checkout…, then confirm the disable action. This is the recovery route when Zide cannot read enough of the configuration to manage its directory selection.
Disable sparse checkout
Click Disable Sparse Checkout. In the Disable Sparse Checkout confirmation, click Disable.
Zide asks before it disables sparse checkout because every repository file will be checked out. This can use significant disk space in a large repository.
While an operation runs
Changing the sparse selection rewrites the working tree, so Zide runs one sparse checkout operation at a time for each repository or worktree.
While an operation runs, Zide disables Enable Sparse Checkout, Disable Sparse Checkout, Add Directories, Exclude, Switch to Directory Selection…, and Check Again, and each tooltip names the operation in progress. Clicking a disabled control, or clicking the same control twice, starts nothing further. A second click on Disable Sparse Checkout while its confirmation is open does not open a second confirmation.
Repositories and worktrees are independent. An operation in one repository never disables the controls in another, and a repository and its linked worktrees can each change their own selection at the same time.
If an operation fails, Zide re-reads the selection from Git and shows what actually remains on disk, together with a notice naming the failure. A failure is not proof that nothing changed: Git can fail after it has already rewritten part of the definition, and the recovery it attempts can fail as well. Read the selection shown below the notice rather than assuming the previous selection was restored. Click Dismiss to clear the notice.
Sparse index
A sparse index uses one entry to represent an excluded directory. This can speed up Git in large repositories. Zide needs Git to read a sparse index.
Staging and the file browser badges show changes inside your sparse checkout. Zide does not mark files as deleted just because sparse checkout excludes them.
You can stage, unstage, and discard changes inside your sparse checkout, including individual files, hunks, and lines. If an action includes a file outside your sparse checkout, Zide refuses the entire action and changes nothing.
In a sparse checkout, Zide uses Git for branch switches, commit checkouts, resets, and branch creation that includes switching. These actions support a sparse index and respect your sparse checkout selection. Zide blocks switches that would overwrite local changes unless you choose Switch anyway.
You can resolve merge, rebase, cherry-pick, and revert conflicts in the file editor and in Staging. You can resolve a conflict outside your sparse checkout if the file is in your working tree. If the file is not there, you can inspect the conflict, but resolution actions are disabled. See Conflicts outside the sparse checkout.
The Submodules tab includes submodules in excluded folders. Zide leaves these uninitialized if they have no working copy. Existing working copies work as usual. See No working copy.
Requirements and limits
Sparse checkout needs Git 2.25 or newer. When an operation needs sparse-checkout support and Zide finds an older Git version, a requirement card replaces the tab content. The card shows A newer Git version is needed with these actions:
- Update Git opens the Git download page.
- Choose another executable… lets you select a different Git executable and checks it.
- Check again checks the current executable again.
- Not now closes the requirement card.
When a later check finds a usable Git, the card shows Git feature is ready. Click Continue to load the Sparse Checkout tab again.
During an active merge or rebase, Zide disables Enable Sparse Checkout, Disable Sparse Checkout, Add Directories, Exclude, and Switch to Directory Selection…. The tooltip reads Cannot modify sparse checkout during merge or Cannot modify sparse checkout during rebase. An Exclude button reads Cannot exclude a directory during merge or Cannot exclude a directory during rebase.
Directory names
Zide sends the exact directory name Git reported, so names with non-ASCII characters, spaces, or a leading dash are included and excluded like any other directory. What a row displays is the last segment of that name; what Zide sends to Git is always the full path Git gave it.
Two kinds of name are limited by Git itself.
| Name | What happens |
|---|---|
A name containing *, ?, [, or \ | Git needs version 2.31 or newer to store these as part of a directory name rather than as a pattern. On an older Git, Zide reports which name it cannot select and changes nothing. |
| A name that begins or ends with a space or a tab | Git trims that whitespace and would select a different directory, so Zide refuses the name and changes nothing. |
If Git ever reports a selection that differs from the one Zide asked for, Zide reports the difference as an error rather than showing the result as the selection you chose.