Branches, log and shelf

Purpose

Three parts of the Source Control module help you work with Git history. The branch bar and the Branches menu show the current branch. They let you switch, create, rename, delete, merge and rebase branches, and fetch, pull and push. The Log tab lists the commits of a branch. The Shelf tab keeps changes that you set aside and want back later. The Commit tab, the list of changed files and the merge banner are in Source control.

Where to find it

• Left sidebar, activity rail: the Source Control icon (tooltip "Source Control"). See Window layout.
• The panel has three tabs: Commit, Log and Shelf.
• The branch bar and the Branches menu are only in the Commit tab. The Log and Shelf tabs have no branch bar.
• The panel works on one Git tree. When the project has worktrees, the list Source control worktree picks the tree: Main working tree or a worktree. Branches, log and shelf all follow this choice. See Source control and Worktrees.
• With no project, the module says "Select a project to see its source control." With no project folder, or a folder that is not a Git repository, the panel shows no tabs. See Source control.

What you see

Branch bar — at the top of the Commit tab, under the merge or rebase banner when one shows.

• Branches button (branch icon, the branch name, a down arrow) — shows the current branch. It reads "detached HEAD" when no branch is checked out. It opens the Branches menu.
• Ahead and behind count, for example "↑2 ↓1" — the commits that the branch has and the remote branch has not (↑), and the reverse (↓). It shows only when the branch has an upstream, or a branch with the same name exists on the remote. Without an upstream, its tooltip reads "No upstream set — compared with <remote branch>. Pull or Push sets it."
• Fetch button (tooltip "Fetch"), Pull button (tooltip "Pull") and Push button (tooltip "Push") — they sync the current branch with its remote. While one remote operation runs, all three go off and show a refresh icon.

Branches menu — opens under the branch bar. Its accessible name is "Branches".

• Local Branches — the heading. Only local branches are listed.
• One row for each branch. A row has, from left to right:
  • A dot and the branch name. The name is a button (accessible name "Check out <name>"). It is off for the current branch.
  • The HEAD mark on the current branch. A branch that a worktree has checked out shows the worktree name instead (tooltip "Checked out in worktree <name>").
  • The merge button (merge icon, tooltip "Merge <name> into current").
  • The rebase button (clock-arrow icon, tooltip "Rebase current onto <name>", accessible name "Rebase onto <name>").
  • The rename button (pencil icon, tooltip "Rename <name>").
  • The delete button (trash icon, tooltip "Delete <name>").
• The current branch row has only the rename button. It has no merge, rebase or delete button.
• New Branch… — the last row, under a divider.

Log tab

• Branches heading and one row for each local branch (shown when the list has loaded). The row of the shown branch is highlighted. The current branch has the HEAD mark.
• History heading — it reads "History · <branch>" when the list shows a branch that is not the current one.
• One row for each commit, newest first. From left to right: a graph lane and the commit message. Under the message: a HEAD tag (only on the commit that is checked out), the author, the short commit code and the age, for example "2 hours ago".
• The graph lane is one lane. Each commit is a dot. A line joins the dots of neighbouring commits. The HEAD dot is bigger and filled. A commit with two or more parents has a short curve in a second colour.
• Load more button — under the last commit, when more history can load.

Shelf tab

• One row for each shelf entry, newest first. From left to right:
  • An arrow button (accessible name "Expand shelf entry" or "Collapse shelf entry").
  • A shelf icon and the entry name. Every entry that Orkestra makes is named "Shelved changes".
  • The marker applied (shown in capital letters, tooltip "Already unshelved") — after you unshelve the entry.
  • Two buttons that show when the pointer is over the row: unshelve (tooltip "Unshelve (apply changes back; keep on the shelf)") and delete (tooltip "Delete (remove permanently)").
  • At the right, the branch that was checked out when you shelved, a dot and the age, for example "main · 3 hours ago". On a detached HEAD only the age shows.
• An open entry lists its files. Each file row shows a file icon, the file name, its folder and a letter: M (changed), A (added), D (deleted, the name is struck through), R (renamed) or ? (new file that Git does not track).
• The Shelf tab has a count of its entries when the list has loaded and is not empty.

How to

Open the branch menu

1. Open Source Control in the left sidebar.
2. Click the Commit tab.
3. Click the Branches button in the branch bar.

Result: the Branches menu opens and lists the local branches. It shows "Loading branches…" for a moment. Click outside the menu or press Esc to close it.

Switch to another branch

Before you start, open the branch menu. See Open the branch menu.

1. Click the name of the branch that you want.

Result: the menu closes. The branch bar shows the new branch and the changed files list updates. If a worktree has this branch checked out, the panel switches to that worktree and does not check out the branch again. If no worktree has the branch, the panel switches to Main working tree and checks the branch out there.

Create a branch

Before you start, open the branch menu.

1. Click New Branch… at the bottom of the menu.
2. Type a name in the field (hint "branch name").
3. Press Enter.

Result: Orkestra creates the branch at the current commit and switches to it. The menu closes. The branch bar shows the new name. Use letters, numbers, dot, dash, underscore and slash in the name. Do not use spaces.

Rename a branch

Before you start, open the branch menu.

1. Click the pencil button of the branch (tooltip "Rename <name>"). The row becomes a text field with the old name.
2. Type the new name.
3. Press Enter.

Result: the menu closes. The next time you open it, the row shows the new name. If you renamed the current branch, the branch bar shows it too. An empty name keeps the old name. If the rename fails, the Commit tab shows the error in a red banner with Retry.

Delete a branch

Before you start, open the branch menu.

1. Click the trash button of the branch (tooltip "Delete <name>"). A dialog opens with the title "Delete branch".
2. Click Delete in the dialog.

Result: the dialog and the menu close. The branch is gone from the list when Git allows it. Click Cancel to keep the branch.

Merge a branch into the current branch

Before you start, open the branch menu.

1. Click the merge button of the branch (tooltip "Merge <name> into current").

Result: the menu closes and Git merges that branch into the current branch at once. There is no confirmation. If the merge has conflicts, the Commit tab shows a merge banner. See Source control.

Rebase the current branch onto another branch

Before you start, open the branch menu.

1. Click the rebase button of the branch (tooltip "Rebase current onto <name>").

Result: the menu closes and Git rebases the current branch onto that branch at once. There is no confirmation. If the rebase has conflicts, the Commit tab shows a rebase banner. See Source control.

Pull the current branch

1. Open Source Control in the left sidebar.
2. Click the Commit tab.
3. Click the Pull button (tooltip "Pull").

Result: Orkestra pulls from the remote. The notice "Pull completed" shows at the bottom of the window. The ahead and behind count updates.

Push the current branch

1. Open Source Control in the left sidebar.
2. Click the Commit tab.
3. Click the Push button (tooltip "Push").

Result: Orkestra pushes the current branch. The notice "Push completed" shows at the bottom of the window. A branch without an upstream is pushed to the remote "origin" and gets an upstream.

Open the Log tab

1. Open Source Control in the left sidebar.
2. Click the Log tab.

Result: the tab shows "Loading commit history…". Then it shows the Branches rows and the commits of the current branch.

Show the history of another branch

Before you start, open the Log tab. See Open the Log tab.

1. Click a branch row under Branches.

Result: the row is highlighted. The History heading adds the branch name. The list shows the commits of that branch. Click the row of the current branch to go back.

Open a commit

Before you start, open the Log tab.

1. Double-click a commit row (tooltip "Double-click to open this commit").

Result: a commit window opens on the active workbench, in the large focused view. If a window for this commit is already open, Orkestra shows that window. See Diff, merge, commit and Git console windows. A single click only highlights the row. The keys also work: Enter opens the row, Space highlights it.

Load older commits

Before you start, open the Log tab.

1. Click Load more under the last commit.

Result: the list holds twice as many commits.

Shelve the current changes

Before you start, the project must have changes. See Source control.

1. Open Source Control in the left sidebar.
2. Click the Commit tab.
3. Click the shelf button in the toolbar (shelf icon, tooltip "Shelve current changes").

Result: the changed files list is empty again. The Shelf tab shows a new entry and a count.

Open the Shelf tab

1. Open Source Control in the left sidebar.
2. Click the Shelf tab.

Result: the tab shows "Loading shelved changes…". Then it shows the entries, or the text "No shelved changes".

Show the files of a shelf entry

Before you start, open the Shelf tab.

1. Click the arrow button of an entry (accessible name "Expand shelf entry"). A click on the entry row has the same effect.

Result: the file rows show under the entry. Click again to hide them.

Unshelve an entry

Before you start, open the Shelf tab.

1. Move the pointer over the entry.
2. Click the unshelve button (tooltip "Unshelve (apply changes back; keep on the shelf)").

Result: the changes come back to the working tree. The entry stays and gets the marker applied. The Commit tab lists the files again.

Delete a shelf entry

Before you start, open the Shelf tab.

1. Move the pointer over the entry.
2. Click the delete button (tooltip "Delete (remove permanently)"). A dialog opens with the title "Delete shelf entry".
3. Click Delete in the dialog.

Result: the entry and its saved changes are gone. Click Cancel to keep the entry.

States and messages

Branches menu

• "Loading branches…" — the list is loading.
• "No local branches." — the repository has no branch yet.
• A red row with the Git error, or "Failed to read branches." — the list could not load. Close and open the menu to load the list again.
• The delete dialog says: Delete branch "<name>"? This cannot be undone. Its buttons are Delete and Cancel.
• Switch, create, rename, delete, merge and rebase close the menu at once. If one of them fails, the Commit tab shows the Git error in a red banner with Retry, which runs the same action again. For example, a name with a character that is not allowed gives "invalid-request". The branch bar keeps the old branch. If a delete fails, the branch stays in the list. See Source control.
• Merge and rebase show no notice. A failed merge or rebase shows an error banner in the Commit tab. See Source control.

Branch bar

• A notice at the bottom of the window, for 6 seconds, with a × button: "Fetch completed", "Pull completed", "Push completed". A failed one reads "Pull failed: <first line of the Git error>". The Commit tab shows the full error in a banner. See Source control.
• Fetch, Pull and Push are off while any remote, merge or rebase operation runs.

Log tab

• "Loading commit history…" — the list is loading. Commits that were already loaded stay on screen during a reload.
• "No commits yet — this branch has no history." — the branch has no commit.
• The Git error, or "Failed to read git log." — the list could not load.

Shelf tab

• "Loading shelved changes…" — the list is loading.
• "No shelved changes" and "Set aside changes from the Commit tab — they return here, restorable any time." — the shelf is empty.
• The Git error, or "Failed to read the shelf." — the list could not load. The tab shows the text instead of the list. Open another tab and then the Shelf tab again to load the list.
• A red banner above the list, with Retry and an x button (accessible name "dismiss error") — an unshelve or a delete failed. The list stays. Retry runs the same unshelve or delete again. The banner stays when the list reloads. It goes away when you click x, when a later unshelve or delete works, or when you switch the selector to another worktree. Messages from the shelf itself: "Shelf entry not found.", "Shelf patch is missing or unreadable." and "Shelf patch exceeds the size cap."
• The delete dialog says: Delete shelf entry "<name>"? This cannot be undone. Its buttons are Delete and Cancel.
• If a shelve fails, the Commit tab shows the Git error in a red banner with Retry (you start Shelve from that tab). Nothing moved to the shelf.
• If there is nothing to shelve (the list still showed changes that are already gone), a notice says "Nothing to shelve: the working tree has no changes". No entry is made.

Limits and tips

Branches

• The menu lists local branches only. It cannot show, check out or delete a remote branch.
• A new branch always starts at the current commit.
• Delete asks Git for a safe delete. Git refuses a branch that it does not see as merged. There is no force option. Delete and rename change local branches only.
• Merge and rebase have no options. There is no interactive rebase.
• Only Delete asks you to confirm.
• In a name field, Enter applies the name. Moving the focus out of the field, for example with Tab, also applies it. Esc closes the whole menu.
• Fetch only updates what Orkestra knows about the remote. It does not change your files. Pull merges the remote work into the current branch. It has no rebase option. Push has no force option. Orkestra uses the remote named "origin". A branch without an upstream pulls from "origin" and gets an upstream.

Log

• The list shows 200 commits at first. Each click on Load more doubles the number. The limit is 2000 commits. At the limit the button is gone.
• The list reloads when you open the Log tab, when you return to the Orkestra window, and when the repository changes, for example when an agent commits in a terminal. A reload shows the current branch again. To reload by hand, open another tab and then the Log tab again.
• The tab has no search, no filter by author and no right-click menu.

Shelf

• Shelving is not Git stash. Orkestra keeps the shelf in a hidden folder inside the repository. Git ignores that folder. If you delete the folder, you lose the shelf. Git stash commands do not list these entries.
• Each Git tree has its own shelf. The Source control worktree list picks which shelf shows.
• Shelve takes all changes at once: staged, not staged, new and deleted files. You cannot pick files. It then sets the files back to the last commit and removes the new files from disk. The button is off when there is nothing to shelve.
• Unshelve works on any branch. It puts every change back as a change that is not staged. A new file comes back as a new file that Git does not track. Git can refuse to apply the saved changes, for example when the files changed since. Then the Shelf tab shows the Git error in a red banner above the list, and nothing is lost. Unshelve never removes the entry.
• You cannot open a file or see a diff from a shelf entry. The file rows only show the files.
• The shelf keeps up to 500 entries. A new entry then pushes the oldest one out of the list.
• The count on the Shelf tab shows after the list has loaded. Open the Shelf tab once to see it.

Related

• Source control — the Commit tab, the list of changes, the merge and rebase banner, the worktree list and the error banner.
• Diff, merge, commit and Git console windows — the commit window that opens from the Log tab, and the Git console.
• Worktrees — the worktrees that the branch menu marks.
• Window layout — how to open the Source Control module.