Work with a repository

Changes and commits

Changes (Ctrl+1) lists every changed file. Its check box includes the file in the next commit; select a file to see its diff.

• Part of a file: click line numbers in the diff to include or leave out single lines, or the bar beside a block to take the whole block. Drag to select several lines.
• Commit: write a summary (Ctrl+G jumps to it) and an optional description, then press Commit or Ctrl+Enter. The gear menu has Bypass Commit hooks, Add Signed-off-by trailer, and Allow empty commit. Co-authors can be added for repositories on GitHub.
• Amend the last commit from the History list’s menu, or the commit form when it offers it. Amending a pushed commit makes the next push a force push, which Puck asks about first.
• Discard changes from a file’s menu, from lines in the diff, or all at once with Branch > Discard all changes (Ctrl+Shift+Backspace). Discarded files go to the Recycle Bin or Trash.
• Filter the list (Ctrl+L) by name, or show only files included in or excluded from the commit, or only new, modified, or deleted files.
• Ignore a file, a folder, or an extension from the file’s menu.

History

History (Ctrl+2) lists the branch’s commits with a graph of their lines. Select one to see its files and diff; select several to cherry-pick, squash, or reorder them. A commit’s menu can revert, reset to it, check it out, create a branch or tag from it, amend, or copy its SHA. Drag commits to reorder them or onto a branch to cherry-pick them.

Branches

Branch > New branch (Ctrl+Shift+N), Rename (Ctrl+Shift+R), and Delete (Ctrl+Shift+D). The branch chip in the top bar, or Branches (Ctrl+3), switches branches.

When you switch with uncommitted changes, Puck asks whether to leave them on the current branch (a stash) or bring them along; Options > Prompts sets the default.

• Update from the default branch (Ctrl+Shift+U) merges it into the current branch.
• Merge into current branch (Ctrl+Shift+M) and Squash and merge (Ctrl+Shift+H) say before you start whether the merge will conflict. Rebase current branch (Ctrl+Shift+E) warns first when the rebase will need a force push.
• Compare to branch (Ctrl+Shift+B) shows the commits one branch has that the other lacks.

Sync

The sync control at the top right does the next useful thing: Publish branch for a branch with no upstream, Pull when behind, Push when ahead, otherwise Fetch. Its menu has the rest.

Puck fetches in the background. A force push uses --force-with-lease, so it never overwrites work it has not seen.

Stashes

Branch > Stash all changes (Ctrl+Shift+S) puts your changes aside on the current branch. Show stashed changes (Ctrl+H) shows them with Restore and Discard. Stashes (Ctrl+5) lists every branch’s stash.

Worktrees

A worktree is another folder checked out from the same repository, on another branch. Repository > New worktree (Ctrl+Shift+W) creates one; the worktree chip in the top bar or Worktrees (Ctrl+6) switches, renames, and deletes them.

Pull requests

For repositories on GitHub while you are signed in: Pull requests (Ctrl+4) lists the open ones with their checks; check one out to work on it. Preview pull request shows the changes before you open one, and Create pull request opens it on GitHub.

Conflicts

When a merge, rebase, cherry-pick, or pull stops on conflicts, Puck lists the conflicted files. Open each in your editor, or keep one side’s version with Use the modified file from that branch, then continue, or abort to go back to where you were. Changes you have not committed that the operation would overwrite are offered a stash first.