Staging

You can use Staging to review changes before committing your files. It supports staging individual files, unstaging all changes at once, and committing your changes.

Navigate Staging

To open Staging, click Git > Staging. Staging opens in the side panel.

Staging refreshes when files or Git state change, including commits made in a terminal. Click Refresh to read the changes again. If another repository operation prevents the read from starting for five seconds, Staging reports that the repository is busy. A background refresh keeps the previous list and marks it as possibly out of date. Retry after the operation finishes; you do not need to reopen the project.

Changed files are organized into the Unstaged section, the Staged section, or the Conflicts section. Each file displays a Git status badge, the file path, and a stage or unstage icon. To group the files by folder, see Show changes as a tree. The following table lists all Git status badges that appear next to each file.

Badge	Description
Modified	Tracked files with changes that are staged or still in the working tree.
Untracked	Files Git does not track.
Added	New files staged for the next commit.
Conflict	Files with unresolved conflicts.
Deleted	Tracked files removed from the working tree or staged for deletion.
Renamed	Files with a staged rename or move. The row shows the new path.

Each section scrolls independently and keeps its position when the file list refreshes. Large conflict lists scroll within their section, leaving room for Unstaged and Staged.

If a background refresh fails, Staging keeps the list and shows Changes could not be refreshed. This list may be out of date. The notice stays until a refresh succeeds.

Click a file to open its changes in a Diff tab. Click another file to show its diff in the same tab. For more information, see Diff viewer.

The section that you click decides which changes the Diff tab shows:

• A file in Staged shows the changes for the next commit. The diff compares HEAD with Staged.
• A file in Unstaged shows the changes that are not staged. The diff compares Staged with Working Tree. An untracked file shows as a new file.

When you stage or unstage a file and it moves to the other section, Staging selects it there, and the Diff tab shows the changes in that section.

To keep a diff while you look at others, pin its tab. A pinned tab is never replaced. A pinned tab, a tab opened with Open Diff in New Tab, or a tab with Ask Zide open keeps showing the same section’s changes when the file moves.

To choose files and discard their changes, click the Discard Changes… icon in the Unstaged section header. When selection checkboxes are on, this icon is Discard Selected Changes…; see Choose files with checkboxes. See Stage, unstage, or discard selected files. To undo the last commit, open the Staging More actions menu and click Undo Last Commit….

To open a diff in its own tab that later files will not replace, right-click the file and click Open Diff in New Tab.

To open a file from Staging in a separate tab, right-click the file and click Open File in New Tab.

A submodule row has a submodule icon button that shows the submodule in the Submodules tab of the current project. Right-click the row for Show in Submodules and Open Submodule as Project, which opens the submodule in its own project tab. A submodule is a folder, so its menu has no Open File commands.

Review a submodule change

A submodule change moves the commit that your repository records for the submodule. The diff shows only the two commit IDs. When you click a submodule row, the Diff tab also shows a section below the Staging banner that tells you what the change does:

• The line starts with Submodule and tells you what changed, for example Submodule advanced 2 commits, Submodule moved back 2 commits, Submodule: histories diverged, Submodule added, Submodule removed, or Submodule: same commit. A count shows only when the change goes in one direction.
• Next are the two commits that Zide compares. For a staged change, they are HEAD and Staged. For an unstaged change, they are Staged and Checked out, the commit that the submodule has checked out.
• Show commits lists the commits that only one side has, up to 50. A diverged history has one list for each side.

Examine a change that moves back before you commit it. It can undo a submodule update that is already committed.

Click a commit ID or a commit card to open that commit from the submodule’s repository. If the submodule is not checked out, or your clone does not have the commit, the commit ID is outlined and its tooltip tells you why.

A submodule can change in both Staged and Unstaged. For example, you stage a new commit for the submodule, and then check out a later commit in it. Staging then shows the submodule in both sections with the Partial badge. Point to the badge to see what it means. The section shows one line for each change. A submodule records one commit, so you stage or unstage all of it.

If Zide cannot compare the commits, the section tells you why, for example Cannot compare. The submodule is not checked out. Zide does not fetch, initialize, or check out a submodule to show this section.

Stage and unstage files

To stage or unstage a file, click the Stage icon or the Unstage icon on the right of the file. To stage or unstage all files, click the Stage All Unstaged Files icon or the Unstage All Files icon in the section header. To stage a group of files, use a folder in Tree View, or check the files and stage them together.

You can also stage, unstage, or discard a file from the Staging banner of its Diff tab. See Staging banner.

Partially staged files

A file is partially staged when some of its changes are staged and others are not. Staging shows the file in both sections, with the Partial badge on each row:

• Its row in Staged shows the changes for the next commit. Click Unstage to remove them from the next commit.
• Its row in Unstaged shows the remaining changes. Click Stage to stage them.

Stage All Unstaged Files also stages the remaining changes of partially staged files.

Renamed files

When you stage a rename or a move, for example with git mv, Staged shows one row with the Renamed badge. The row shows the new path. Point to the row to see the old path and the new path. Click the row to see the rename in a Diff tab. The diff compares the old path in HEAD with the new path in Staged. See Renamed, moved, and copied files.

Click Unstage on the row to unstage both paths. Unstaged then shows the old path as deleted and the new path as untracked. Staging pairs the old path and the new path only after both are staged. When you stage both paths again, Staged shows one row again.

Git finds a rename when the staged file is similar to the old file. If you stage large changes to a renamed file, Git and Staging show a deleted file and an added file instead.

To unstage only one of the two paths, use Unstage Files…. See Stage, unstage, or discard selected files.

Show changes as a tree

To group the changes by folder, click More actions for Staging, then click Tree View under View. Click Tree View again to show lists.

In Tree View, Unstaged and Staged each show their files under their folders. Folders come first, in name order, and then files. A folder that holds only one other folder shows as one row, for example src/modules. Lines join each row to its folder. Click a folder’s name or arrow to collapse or expand it. Collapse All and Expand All in More actions do this for every folder.

Staging remembers Tree View and the collapsed folders for each repository, also after you restart Zide.

A folder row has a Stage Folder or Unstage Folder icon on the right. It stages or unstages the changed files under the folder in that section, including files in collapsed folders. When the filter is set, it acts only on the files that the filter shows.

Right-click a folder for Stage Folder or Unstage Folder, Show in File Browser, Copy Folder Path, Collapse All, and Expand All. A folder in Unstaged also has Discard Changes in Folder…, which opens the Discard Changes dialog with only the files of that folder.

A folder in Staging is a group of changed files, not a folder on disk. A folder action does not include files without changes, conflicted files, or another repository in the folder. If it skips a path, for example a nested repository, a message says so.

Filter files

Click the filter icon on the Staging title line, or press Ctrl+F (Cmd+F on macOS). Type part of a path in Filter files. Both sections show only the paths that contain the text, and a Path chip shows the filter. Click x on the chip to clear the field, remove the chip, and show all changed files in both sections. A section with no matching files shows No results. Setting or clearing the filter does not change which files are checked.

Choose files with checkboxes

To check files and stage them together, click More actions for Staging, then click Show Selection Checkboxes under In Activity Panels. This setting applies to all activity panels. It is also in Settings > Other Settings > Input.

When checkboxes are on:

• Each file and folder row has a checkbox instead of the Stage or Unstage icon.
• Check a folder to check the changed files under it, including files in collapsed folders. When the filter is set, a folder covers only the files that the filter shows. When only some of those files are checked, the folder checkbox shows a mixed state.
• The checkbox in a section header checks or clears all files in that section, including files in collapsed folders and files that the filter hides.
• Stage Selected in the Unstaged header stages the checked files. Unstage Selected in the Staged header unstages them. The number beside the action is the number of checked files. In a narrow panel, the action shows only its icon and the number.
• Discard Selected Changes…, the trash icon in the Unstaged header, opens the Discard Changes dialog with only the checked files. The dialog shows what it restores and deletes before you confirm.
• These actions are unavailable until you check a file. Their tooltip is Select files first.
• When the filter hides checked files, a line under the section header shows how many. The actions include these files.

The checks in Unstaged and Staged are separate. A partially staged file can be checked in one section and not in the other.

Click a file name to open its diff. Your checks stay. In other Zide lists, a click clears the selection. In Staging, the checks stay so that you can check files, review other diffs, and then stage the checked files.

• Ctrl+click (Cmd+click on macOS) checks or clears a file.
• Shift+click checks the files from the last file that you checked or cleared to the file that you click. Shift+click again from the same file to change that range. Other checks stay.

The checks also stay when you collapse a folder, change the filter, or turn checkboxes off and on again, and when the list refreshes. After an action, the files that it completes lose their checks. Files that fail stay checked, so that you can try again. A file that appears later is not checked.

Use the keyboard

When checkboxes are on, each section is a list that you can use with the keyboard. The rows of a section share one Tab stop.

Key	Result
Up Arrow, Down Arrow, Home, End	Move between rows. The checks do not change.
Space	Checks or clears the row. On a folder, checks or clears the files under it.
Shift+Up Arrow, Shift+Down Arrow	Check a range of rows.
Ctrl+A or Cmd+A	Checks all rows that show.
Escape	Clears the checks in this section.
Enter	Opens the diff of a file, or collapses or expands a folder.
Right Arrow, Left Arrow	In Tree View, expand or collapse a folder, or move between a row and its folder.
Menu key or Shift+F10	Opens the menu for the row.

Stage, unstage, or discard selected files

Click More actions for Staging. Click Stage Files…, Unstage Files…, or Discard Changes….

All files in the dialog are selected when it opens. To change the selection:

• Type a file path or part of a path in Filter files. The filter does not change which files are selected.
• Select or clear a file’s check box.
• Select or clear Select All. This changes the selection for all listed files, including files hidden by the filter.

The count shows how many files are selected and how many selected files the filter hides. Click Stage, Unstage, or Discard to apply the selection.

For a partially staged file, Stage stages its unstaged changes. Unstage removes its staged changes from the next commit and keeps the working file. Discard removes its unstaged changes and keeps its staged changes.

The Unstage Files dialog lists the two paths of a staged rename as two files. Each shows Renamed to or Renamed from and the other path. If you unstage one path, the other path stays staged, and the rename ends. Use this to keep the staged version of the new file but not the deletion of the old one.

The Discard Changes dialog shows how many selected tracked files have changes to discard. It also shows how many selected untracked files it will permanently delete. Discard applies these changes without another confirmation.

The dialogs do not list conflicted files. Stage Files and Discard Changes also do not list nested repositories. Discard Changes also does not list submodules. A note shows how many files of each type are not listed.

If Zide reports that the repository changed, the action did not start. Click Review Updated List to load the list again. Files you selected stay selected if they are still listed. New files are not selected.

If some files fail, the dialog lists them and any files that were not attempted. Click Review Remaining to load the list again. Only the failed and not attempted files that are still listed are selected. The Console shows why each file failed.

Filters and the post-checkout hook

Some repositories change files as Git writes them, for example with Git LFS, another filter, or a working tree encoding other than UTF-8. Some also have a post-checkout hook. In these repositories, Discard Changes restores tracked files through Git, both from the file’s shortcut menu and from the dialog. The files then match what Git would write, and Git runs the hook once for the whole discard. If Git cannot restore a file, Zide reports that file as failed and does not delete the selected untracked files. If only the hook fails, the discard stays done. See A hook failed after a checkout or discard.

Files that Git filters

Some files change when Git stages them. Git LFS replaces a tracked file with a pointer. A repository can also set a clean filter, or a working tree encoding other than UTF-8, in .gitattributes. Zide stages these files through Git, so the index gets the same content as git add gives it. This needs Git. For a Git LFS file, it also needs Git LFS.

If a filter that the repository marks as required fails, Git stages nothing:

• Stage and Stage All Unstaged Files stage none of the files and show the error.
• Stage Files… stages the other selected files and lists the file whose filter failed.
• Save and Stage in a conflicted file saves the file but does not stage it. Fix the filter, then click Retry Stage.

The text that a diff shows for a filtered file is not what Git stores. For this reason, you cannot stage, unstage, or revert a hunk or a line of it. Stage or unstage the whole file instead. This also applies to a file whose filter changes it only when Git writes it to your working tree, although Zide stages that file without Git.

Stash a file

Right-click the file. Click Stash This File…. The Push Stash dialog opens with only that file selected. Click Stash Selected Files, or Stash if this is the only selectable file in the scope. Changes in other files stay in your working tree and index. For more information, see Stash selected files.

Ignore an untracked file

You can ignore an untracked file from its shortcut menu. For the rule choices and where the rule is written, see Ignore files and folders.

Track a file with Git LFS

Right-click a file and select Track with Git LFS… to add a Git LFS pattern for it. If a rule already covers the file, the item is Open Git LFS. For the pattern choices and what you must stage afterwards, see Track a file from Staging or the file browser.

Commit and amend staged files

Use Generate beside Commit Staged Changes or Amend Previous Commit to draft both the subject and description with Zide. The label stays visible when the fields contain text. In a narrow pane, the label hides before the button wraps; the icon keeps its tooltip. Widen the pane to restore the label. Hover or focus the button to see both affected fields. Existing text opens a review before replacement, and applied results offer Undo. To expand the message editor, use the expand button beside the Commit and Amend tabs. It opens in the selected mode, with Generate in its header. The expand button is disabled when Commit has no staged files or Amend has no previous commit. You can still expand Amend to change only the previous commit message. Done returns the edited subject and description to Staging. Review the result, then click Commit or Amend.

You can commit changes once your files are staged. To create a commit, complete the following steps.

1. In Staging, click Commit.
2. Enter the commit message and optionally a description of the commit.
   Commit templates are loaded automatically if a .gitmessage file exists.
3. Click Commit.

You can also amend files to your previous commit. To amend your files to a commit, complete the following steps.

1. In Staging, click Amend. Zide pre-fills the commit message from the previous commit.
2. Click Amend.
3. In the Amend Commit dialog, click Amend.

Advanced Options has these settings for a commit or amend:

• Skip hooks skips pre-commit hooks.
• Signing decides whether this commit is signed. Use Git settings follows your signing settings. Its label shows what the settings do, for example Use Git settings (sign with SSH). Select Sign or Do not sign to change only this commit. After the commit, Signing goes back to Use Git settings.

While Staging commits or amends changes, the button shows a spinner and Committing… or Amending…. You cannot stage, unstage, or discard changes during this time. You can still click a file to see its diff.

Finish a merge, rebase, cherry-pick, or revert

When a merge, rebase, cherry-pick, revert, or patch series pauses on a conflict, the conflicted files appear in the Conflicts section and the Project Header replaces the Branch or Worktree control with a conflict banner. Resolve each file, then finish the operation from that banner: click Commit for a merge, cherry-pick, or revert, or Continue for a rebase, a squash merge, a cherry-pick of several commits, or a cherry-pick or revert without a commit. A patch series is what git am applies. Stage the resolved files, then click Continue to commit the patch with its own author and message. While a patch series or a cherry-pick of several commits is paused, the commit button in Staging is unavailable, because Continue commits each patch or commit with its own author and message. See Cherry-Pick Commits. To abort, click the operation label in the banner, select the abort action at the bottom of the menu, then confirm. See Project tabs.

The Git-operation header and Staging activity icon are red while conflicts remain, and amber when the operation is ready for you to continue or commit.

Resolve a conflicted file

Select a conflicted file to see its two sides in a Diff tab. The conflict bar above the sides names the conflict and shows the actions that apply to it. These can include Stage As-Is and one control for where you resolve the file:

• Resolve in Zide opens the file in the editor with controls for each conflict.
• Open in tool starts the external merge tool that Git is configured to use.

When both are available, click the caret to choose one. Zide remembers your choice. With no external tool configured, there is one button and no caret.

Stage As-Is stages the file as it is in the working tree, including your edits. If the file is missing, it stages the deletion. It is not available for a binary conflict or a file deleted on both sides.

To see what Stage As-Is will stage, click Working file view in the Diff tab header. This view shows the file as it is on disk and highlights conflict marker lines. To choose a version, click Compare Versions.

After you remove all conflict markers and save a text file, it stays in Conflicts until you stage it. Its row shows a + button to stage the file in place of the conflict type. The Diff tab’s conflict bar turns green and shows Conflict: No markers remaining, with Stage instead of Stage As-Is as its main action. Zide checks for markers again before staging and refuses if any remain. Removing markers does not prove the merge is correct, so review the file before staging.

Click Last file commit beside a branch name to see the last commit that changed this file on that side, with its message and date. In a narrow column, click the history icon. Click the commit id to open the commit. This commit may not have changed the conflicting lines. For a deleted side, the button reads Deleted in and the id of the commit that deleted the file. If both sides share the commit, only the left column has the button.

Resolving in an external merge tool

Open in tool launches the merge tool Git is configured to use, with the base, local and remote versions of the file.

Closing the tool is not the same as resolving the conflict, so Zide stages the file only when the evidence says it was resolved: the tool saved something, no conflict markers remain, and the tool did not report failure. If you close the tool without saving, or save a file that still has markers in it, the file stays in the Conflicts group and the Console says why.

Zide reads mergetool.trustExitCode for the third of those checks, the same way Git does. It is off by default, because most tools do not report a declined merge in their exit status.

Conflicts with no markers

A conflict is not always two versions of some text. A file one side changed and the other deleted, a file both sides deleted, a binary file, a file too large to merge, and a conflicted submodule all have nothing to edit. Zide shows each of them in the way that suits it, and offers only the choices that conflict has:

Every conflict appears as two columns with the branch name above each one, because every conflict has two versions. What fills a column depends on what that version holds:

Conflict	What fills the columns
Both sides changed the text	The two versions, as a diff
One side changed the file, the other deleted it	The surviving file as text or hex; the other column’s label is marked (deleted)
Binary Zide can preview	Image, audio, or video previews; Hex view shows each version’s bytes
Binary it cannot preview, or a file too large to read	Each version in hex; a version larger than 256 MiB shows its size instead
A submodule	The commit each side pins: its short id, its message, and its date
Deleted on both sides	Where each side moved the file to, when Zide can tell

The conflict bar names the conflict. An action for one version is in that version’s column header:

Conflict	Choices
Both sides changed the text	Use This Version under either side. It stages that whole version. To combine the two, resolve the file in the editor instead.
Changed on one side, deleted on the other	Keep File for the branch that kept it, Delete File for the branch that removed it
Deleted on both sides	Delete File in the conflict bar
Binary, or too large to merge	Use This Version under either side
Submodule	Use This Version under the commit it would pin

Why a file deleted on both sides is a conflict

Deleting the same file on both branches does not cause a conflict. A conflict where both sides deleted the file usually involves a rename, such as each side moving the file to a different path. Zide shows any new paths it can identify. Delete File stages the deletion of the old path. Content that moved to a new path is not lost.

Taking a choice resolves and stages the file at once. Only a choice that stages a deletion asks you to confirm first.

Conflicts outside the sparse checkout

A conflict in a folder outside your sparse checkout stays in the Conflicts section. If Git writes the file into your working tree, you can resolve it as usual.

If the file is not in your working tree, you can inspect the conflict, but resolution actions are disabled. Zide does not create the file. Commit and Continue stay blocked until the conflict is resolved. To finish, use Git outside Zide to resolve the conflict or, if Git allows it, add the folder to your sparse checkout and resolve it in Zide. To stop, abort the operation from the conflict banner.

Resolving every conflict does not finish the operation. Once all conflicts are resolved, the Conflicts group stops warning and reads No conflicts, and the operation stays open until you finish it from the conflict banner in the Project Header.

When a resolution leaves nothing to stage and nothing unstaged, which happens when you resolve a conflict in favor of the side that already matches your branch, Staging reports All conflicts resolved and names the banner control that completes the operation. It reports Working tree clean only when there is no unfinished operation.

Edit a commit during an interactive rebase

When an interactive rebase stops at a commit set to Edit, Staging says Rebase stopped to edit and selects Amend, unless you already typed a commit message. You can amend that commit, or click Undo Last Commit… in the Staging More actions menu to split it into new commits. When the stopped commit is the first commit of the branch, you can only amend it, and Undo Last Commit… is disabled. Then click Continue in the Project Header. See Edit or split a commit.

Assist with This

Right-click a changed file and point to Assist with This.

Under Zide Assist, click Add to Conversation to attach the file to a Zide Assist tab. You can also drag the file into a Zide Assist tab. For more information, see Attach items to a message.

Under Ask Zide, click Open Ask Zide. Zide opens the file in a Diff tab with an Ask Zide panel beside it. In the panel, click Summarize Changes or Review Changes. For a conflicted file, click Explain Conflict, Suggest Resolution, or Review Conflict. Ask Zide does not edit, stage, or resolve the file. See Ask Zide beside a tab.