Changes and commits

Purpose

The Source Control module shows what changed in the Git checkout of your project. You stage files, write a commit message and commit. You can also fetch, pull and push. It works on the main folder of the project or on one of its worktrees. Branches, the log and the shelf are in Branches, log and shelf. The diff, merge and Git console windows are in Diff, merge, commit and Git console windows.

Where to find it

• Left sidebar, activity rail: the Source Control icon (tooltip "Source Control"). Click it to open the module. See Window layout.
• The module works on the active project. With no project it shows "Select a project to see its source control." The project needs a folder on disk with a Git repository. See "States and messages".

What you see

Tab strip

• Commit — the tab that this chapter describes. A number shows how many files changed (hidden when none).
• Log and Shelf — see Branches, log and shelf. A number on Shelf shows how many entries it holds.

Worktree selector — shown only when the project has a worktree. It works for all three tabs. It is a colour dot and a drop-down list (accessible name "Source control worktree"). The first entry is Main working tree. The others read "<worktree name> · <branch>". The dot has the colour of the chosen worktree.

In-progress banner — shown only while a merge or a rebase waits for you.

Branch bar

• Branches button — shows the current branch name, or "detached HEAD". It opens the branch menu. See Branches, log and shelf.
• "↑<n> ↓<m>" — commits your branch is ahead of and behind the remote branch. Shown when the branch has an upstream, or the remote has a branch with the same name.
• Fetch, Pull and Push — icon buttons at the right end (tooltips "Fetch", "Pull", "Push"). How they work is in Branches, log and shelf.

Toolbar — icon buttons. The tooltip is the name. From left to right: Refresh; Stage all (check icon); Unstage all; Group by directory (folder icon, on by default); Collapse all; New group (plus icon); Shelve current changes (see Branches, log and shelf); Git console (terminal icon). The text "<n> staged" is at the right end.

Changes list — scrolls. Groups, from top to bottom: Changes (files that Git tracks; with your own groups, only the files in no group), your own groups if any, and Unversioned Files (new files that Git does not track).

• A group header has an arrow (fold or unfold), a check box, the name, the number of files and an x button (tooltip "Discard all changes in <group>"). In flat view, Changes has a small tag Default.
• A folder row (folder view only) has an arrow, a check box, a folder icon, the name and the number of files below it. A chain of folders with nothing else shows as one row, for example "src/main/auth".
• A file row has a check box, a file icon, the file name, the folder path (flat view only) and a one-letter tag: M (modified), A (added), D (deleted, name struck through), R (renamed), U (conflict) or ? (not tracked). Two small buttons can follow: an x button (tooltip "Discard changes"), on every row, and a small arrow button (tooltip "Return to Unversioned Files"), only on a new file that Git tracks but did not commit. A nested Git repository shows the text "commit pointer, not files".

Commit box — under the list: a notice with the button Stage them (only when a file is partly staged); the text area (hint "Commit message"); the check box Amend with a robot button at the right (tooltip "Generate commit message from the staged diff (Helm)"); the button Commit, with the staged count in brackets, for example "Commit (3)"; and a small button right of Commit (tooltip "Commit and Push"). A red error banner can show above the box.

How to

Choose the worktree to work on

Before you start, the project needs at least one worktree. See Worktrees.

1. Click the drop-down list under the tabs (accessible name "Source control worktree").
2. Click Main working tree, or the name of a worktree.

Result: the panel reads the chosen checkout. The branch bar, the list, the commit box and the push and pull buttons all act on it. Orkestra saves your choice with the project.

Open the diff of a changed file

1. Double-click a file row.

Result: a diff window opens on the active workbench. A staged file compares the last commit with the staged version. Other files compare the last commit with the file on disk. A file with a conflict (tag U) opens the merge window instead. See Diff, merge, commit and Git console windows.

Stage or unstage files

1. Click the check box of a file row, of a folder row or of a group header.

Result: an empty box gets a tick and the files count in "<n> staged". A box with a tick becomes empty. A folder or group box stages all files below it, or unstages them when all are staged already. A file in Unversioned Files gets added to Git when you stage it.

Stage or unstage all changes

1. Click Stage all.

Result: every file in the list gets staged, Unversioned Files too. To undo it, click Unstage all. It is off when no file is staged.

Stage the rest of a partly staged file

Before you start, look for a file whose box shows a dash. You staged it, and then it changed again.

1. Click Stage them in the notice above the commit message.

Result: Orkestra stages the newest version of every such file. The notice goes away. You can also click the dash box of one file.

Commit staged changes

Before you start, stage at least one file.

1. Click the text area (hint "Commit message").
2. Type the message.
3. Click Commit.

Result: a notice says "Commit created". The message field is empty. The committed files leave the list.

Write the commit message with Helm

Before you start, stage at least one file.

1. Click the robot button (tooltip "Generate commit message from the staged diff (Helm)").

Result: Helm reads the staged changes and writes a short message. It replaces the text in the message field. Read it and change it before you commit.

Amend the last commit

1. Click the Amend check box.
2. Click the text area (hint "Commit message").
3. Type the full new message.
4. Click Commit.

Result: Git replaces the last commit with a new one. It has your message and the staged changes. Commit works with no staged file when Amend is on.

Commit and push in one step

Before you start, stage a file and type a message.

1. Click the small button right of Commit (tooltip "Commit and Push").

Result: Orkestra commits, then pushes. A notice says "Commit & Push completed". If the push fails, the commit stays and the message field is empty. The red error banner shows the push error. Retry in the banner runs only the push again; it does not make a second commit. If the commit fails, your message stays and Retry runs both steps again.

Discard the changes of a file

1. Click the x button on the file row (tooltip "Discard changes").
2. In the dialog Discard changes, click Discard.

Result: a tracked file goes back to its last commit, and its staged version is dropped. A file in Unversioned Files is deleted from the disk. A notice says "Discarded 1 file". The dialog text is "Discard changes in <n> file(s)? Untracked files will be deleted. This cannot be undone." Click Cancel to keep the file. If the discard fails, the red error banner shows the reason; Retry discards the same files again.

Tip: the x button of a group header (tooltip "Discard all changes in <group>") does this for the whole group. For Unversioned Files, it deletes all those files.

Return a new file to Unversioned Files

Before you start, find a new file in Changes with the tag A.

1. Click the small arrow button on the file row (tooltip "Return to Unversioned Files").

Result: the file moves to Unversioned Files. It stays on the disk.

Switch between folder view and flat view

1. Click Group by directory.

Result: the button is on (pressed) by default. When on, the files sit under folder rows. When off, one flat list shows each file with its folder path. The button is off when the list is empty.

Fold or unfold a group or a folder

1. Click the name of a group header or of a folder row.

Result: the rows below hide or show. Unversioned Files and its folders start folded. All other groups and folders start open. Collapse all folds every group and folder. There is no "expand all" button.

Create a group and move files into it

Before you start, the list needs at least one changed file.

1. Click New group.
2. Press the mouse button on a file row in Changes.
3. Drag the row over the header of New Group.
4. Release the mouse button.

Result: the file is now in the group. The new group is named New Group. Drag a file onto the Changes header to take it out of its group.

Rename a group

1. Double-click the group name (tooltip "Double-click to rename"). The pencil button (tooltip "Rename group") does the same.
2. Type the new name.
3. Press Enter.

Result: the group has the new name. An empty name changes nothing. The trash button on the group header (tooltip "Delete group (files return to Changes)") deletes the group. Its files stay in Changes.

Continue a merge or rebase

Before you start, resolve the conflicts. Double-click each file with the tag U, then use the merge window. See Diff, merge, commit and Git console windows.

1. Click Continue in the banner.

Result: Git finishes the merge or the rebase. The banner goes away.

Abort a merge or rebase

1. Click Abort in the banner.
2. In the dialog Abort merge or Abort rebase, click Abort.

Result: Git drops the merge or the rebase and goes back to the state before it. The dialog text is "Abort the in-progress merge? All progress will be lost." (or "rebase").

Initialize Git in a folder

Before you start, open Source Control for a project whose folder has no Git repository.

1. Click Initialize Git.

Result: the button reads "Initializing…" for a moment. Then the normal panel opens. The new repository has no commit yet. All files show in Unversioned Files. From now on the panel also updates by itself when an agent commits in this folder, while Watch Git for changes is on. If Git cannot create the repository, a red error banner with Retry shows below the button, and a notice says "Initialize Git failed: <first line of the error>".

Open the Git console

1. Click Git console in the toolbar.

Result: the Git console window opens on the active workbench. It lists the Git commands that Orkestra runs. See Diff, merge, commit and Git console windows.

States and messages

Panel states

• No project folder: "Set the project's location on disk (edit the project in the top-bar switcher) to see its source control." See Projects.
• First load: "Loading source control…". Later reads keep the old list on screen.
• Read error: the text of the error, or "Failed to read git status."
• Not a Git repository: the whole panel, with no tabs, shows the title "Not a git repository", the text "<project name> isn't under version control yet. Initialize a git repository here to use Source Control.", the button Initialize Git, and a Details line. Details shows the raw Git message.
• Clean tree: "No changes — the working tree is clean." The toolbar buttons Stage all, Group by directory, Collapse all, New group and Shelve current changes are off.
• A new group with no file: the hint "Drag files here".
• Helm cannot write a message: a red line under the Amend row, for example "Stage changes first to generate a commit message." or "The engine returned no usable commit message." Your text stays.
• A remote action runs: Fetch, Pull, Push, Commit and the Commit and Push button are off, and their icons change to a refresh icon.

Commit and Commit and Push are off while the message field is empty, or while no file is staged and Amend is off.

Check box states

• Tick — fully staged. Empty — nothing staged.
• Dash — only part is staged. For a file: you changed it again after you staged it. For a folder or group: some files are staged and some are not.
• A dash on a file has the tooltip "Some changes in <path> are not in the index and will not be committed. Click to stage them." A click stages the newest version.
• A staged file that you deleted from disk afterwards cannot be staged again here. Its tooltip adds "This file is deleted from disk, so its remainder cannot be staged here." For a folder or group, the tooltip is "Deleted file remainders cannot be staged here."

Partly staged notice — above the message field: "<n> partially staged file has changes outside the index that will not be committed." (or "files have"). The tooltip of Stage them is "Stage every available remainder so the current working-tree changes are included." When only deleted files remain, it is "These remainders are deleted from disk and cannot be staged here yet."

Merge or rebase in progress

• The banner text is "Merging — resolve conflicts, then continue" or "Rebasing — resolve conflicts, then continue".
• Continue is off while a conflict is open. Its tooltip is "Resolve and stage all conflicts to continue". Both buttons are off while another Git action runs.
• The list shows one group named Conflicts in place of Changes. It holds all tracked changes. Your own groups are hidden until the merge or rebase ends. They are not lost.
• A row for a conflict has a merge icon and the tooltip "Double-click to resolve conflict".

Nested Git repository — when you stage a folder that holds its own Git repository, the dialog Embedded repository detected opens. It says "Before staging <paths>, choose how to record this embedded repository." The buttons are:

• Stage as submodule pointer — records the folder as a pointer to its commit.
• Add to .gitignore — adds the folder to the ignore list of the project, so Git leaves it out.
• Absorb its files — removes the inner Git history folder and stages the files in this repository. It shows only when it is safe. If it is not, the text adds "Absorb is unavailable for <paths> because its .git entry is symlinked."
• Cancel — stage nothing.

Error banner (red, above the commit box, with an x button, accessible name "dismiss error"). It shows the error of a failed Git action that you started from the Commit tab, the toolbar or the branch menu: stage, unstage, return to Unversioned Files, commit, Commit and Push, discard, shelve, fetch, pull, push, merge, rebase, and a branch checkout, create, rename or delete. A branch action that fails closes the branch menu, and its error shows here. The list stays usable. The banner has the button Retry, which runs the same action again with the same files or names. Retry is greyed out while a fetch, pull, push, merge or rebase (or its abort or continue) runs in the same folder. If it fails again, the banner shows the new error. If a Git action fails with no error text, the banner says "Git operation failed". The banner stays when the panel reads the status again, for example when you return to the window. It goes away when you click x, when a later Git action from this tab works, or when you switch the selector to another worktree. Texts:

• "Commit aborted — pre-commit hooks modified files. Review & re-stage them, then commit again." A Hook output line shows the hook text. Your message stays in the field.
• "Repo busy — an agent may be running git. Retry?"
• "Authentication failed — check your git credentials or SSH key for this remote." (with a Details line that shows the raw Git text)
• "The remote has commits you don't have — Pull first, then Push." (with a Details line)
• "No remote is configured for this repository." (with a Details line)
• "Branch '<branch>' is not on remote '<remote>' yet — Push it first to publish it and set its upstream."
• "Remote operation timed out after 60s — the remote did not respond."
• Any other error shows the text that Git returns.

Notices at the bottom right — small cards above the status bar. Each has an x button (tooltip "Dismiss") and goes away after 6 seconds.

• Success: "Commit created", "Fetch completed", "Pull completed", "Push completed", "Commit & Push completed".
• Failure: "<Action> failed: <first line of the error>", for example "Push failed: …". The text is cut after 200 characters.
• Failure of Initialize Git: "Initialize Git failed: <first line of the error>".
• Warning: the text that Git printed although the action worked. Orkestra leaves out the normal progress lines of Git, for example "Switched to branch 'main'", "To <remote address>", "Everything up-to-date" or the hint about init.defaultBranch after Initialize Git. When only such lines are left, there is no warning. Lines that start with warning:, error:, fatal:, remote: or another hint: stay in the warning.
• Discard: "Discarded 2 files" (or "Discarded 1 file").
• Shelve when there is nothing to shelve (the files changed back outside Orkestra, but the list still shows them): "Nothing to shelve: the working tree has no changes", in the warning colour.
• Stage, unstage, merge, rebase, branch and other shelf actions give no success notice. A failure of these shows only in the red banner.

Limits and tips

• Source Control stages whole files. It cannot stage single lines or parts of a file.
• Groups are only for your own order. Commit takes every staged file, in any group. A group belongs to one worktree and Orkestra saves it with the project. A file that you commit leaves its group.
• Only files that Git tracks can move between groups. Files in Unversioned Files cannot.
• Unstaging a new file does not make it unversioned. It stays in Changes with an empty box. Use the arrow button (tooltip "Return to Unversioned Files") to return it.
• Discard also removes the staged version of a file. It cannot be undone.
• Amend does not fill the message field with the old message. It also stays on after a commit. Clear it yourself.
• The message field, the fold state and the Group by directory setting are not saved. They reset when you open Log or Shelf, or when you switch the project.
• The panel refreshes when you return to the Orkestra window. It also refreshes by itself within about a second when Git changes in the folder, for example when an agent commits in a terminal. This refresh keeps the branch and the number of commits that the Log tab shows. If that branch is gone, the Log tab shows the current branch. The setting Watch Git for changes turns the automatic refresh off (see Settings); then the panel refreshes only when you return to the window, click Refresh, or act in Orkestra. Refresh reloads it at once.
• The robot button uses the default Helm engine. See Settings: Helm.

Related

• Branches, log and shelf — the branch menu, the Log tab and the Shelf tab.
• Diff, merge, commit and Git console windows — the windows that open from this panel.
• Worktrees — create the worktrees that the selector lists.
• Settings: Helm — the engine that writes commit messages.