Save a version with Git

7 minute read · Projects & Git

A Git commit saves a named version of your project locally. It gives you a concrete point to review later as the app changes.

• Save one understandable change
• Switch branches directly
• Stash selected files
• Understand synchronization controls
• Resolve a conflict with evidence
• Use your GitHub or GitLab remote
• Work through Git Flow
• Source Control and history controls

Save one understandable change#

First choose a project or branch badge directly below the Source Control heading. Folder icons identify the main project folders; fork icons identify active, unmerged worktrees. A check mark and stronger colour identify the checkout being reviewed. Hover to confirm the parent and full path when names look similar. The changed-file count belongs to that checkout, not all projects combined.

Open source control and confirm the checkout and branch. Inspect staged, unstaged and untracked files. Use explicit staging if the commit should contain only part of the current work; otherwise review the full change set before choosing the all-changes commit action. Write a message that explains the resulting behavior, such as “Keep article edits after reload”. Commit-message assistance proposes text for review, not permission to commit without checking the files.

Selecting a badge changes the repository you inspect and act on. It does not move a chat to that branch. Choose the chat's working copy through Chat menu → Project & worktree…; use Review & merge there to finish isolated work. The tool panel keeps your chosen dimensions when you switch projects in this workspace.

Manual commit is available independently of an active agent. It does not require the automatic-commit proof conditions, so you remain responsible for choosing the right snapshot. A Git error must be resolved before treating the commit as saved.

Switch branches directly#

Use the compact branch picker to select a local branch, including when you accidentally started a release branch. The check mark identifies the current branch; hover a row for its details. Git Flow operations stay in the separate Git flow icon menu.

Manual branch switching stays available while an agent is working. Local changes are carried across when Git can preserve them; if the target would overwrite a changed file, switching stops and asks you to commit or stash first. A branch occupied by another worktree cannot be selected here. A Git operation already in progress must finish before another begins. Review which checkout the agent is using before changing its branch.

Auto-commit still checks the tested snapshot. If you change the branch or HEAD while its tests are running, auto-commit skips the commit and leaves the files for manual review. See automatic commit conditions.

Stash selected files#

Select one or more changed files in Source Control, right-click a selected row and choose Stash selected files. Right-clicking an unselected row targets that file. Vortex generates a descriptive stash message from the selected files. Other modified files remain in the working tree.

A selected file is stashed as a whole file, including its staged and unstaged changes. Review the selection before stashing. Open … → Stashes & history actions… to inspect and restore a saved stash; restoration can require conflict resolution if the checkout changed. Stash all changes… is a separate action for the full change set.

Understand synchronization controls#

Fetch refreshes remote information. Pull brings remote changes into the current checkout; push sends local commits to the remote. Publish branch is a distinct action for a branch that needs an upstream. The synchronize action pulls when behind and pushes when ahead, subject to the current checkout conditions. Review incoming/outgoing counts and branch information before invoking it.

A commit stays local until you explicitly push. Successful tests or automatic commit do not authorize a push or deployment. A dirty checkout, an active operation or a changed branch may require attention before a mutation can continue.

Resolve a conflict with evidence#

Read which files conflict and which operation stopped. Inspect both intended changes, resolve the content and run the relevant checks again. Avoid discarding all local work just to make a pull succeed. Branch history shows bounded commits, parents, refs and tags so you can identify the intended base.

Git flow feature/release/hotfix operations use the configured conventional branches. Finishing a flow should identify the target and report partial failures; it does not silently authorize tagging, pushing or deployment. For independent checkout work, use worktrees.

Use your GitHub or GitLab remote#

Vortex works with the remotes already configured in the repository. It has no separate GitHub or GitLab account sign-in. Fetch, pull and push use the Git and SSH credentials already set up on this computer, such as an SSH key or your system credential helper. Vortex does not show an interactive password prompt, so a push without working credentials fails with Git's error.

To start from a hosted repository, choose Clone repository, paste the Repository URL and choose Clone and open. To add a remote to an existing checkout, use Add Remote… in the remote menu; Disconnect Remote… removes it from the checkout. Create the repository, review pull or merge requests and manage protected branches on the hosting website.

Check the remote URL and branch/upstream in Source Control before publishing a branch. A denied push may need repository permission, a review or a different target branch rather than another local commit. Never paste a token into a chat or a remote URL.

Work through Git Flow#

Open Source Control, then the Git flow icon beside its branch controls; hover it to see its label. Use feature, release or hotfix operations when the repository follows those conventional branches. Inspect the configured base and current branch before starting. Keep the change bounded, review its diff and run the project's checks before finishing it.

The finish dialog identifies its target branches and distinguishes Finish branch from Finish & Push. Review the selected tag, branch cleanup and publishing options before confirming.

If local merges or tag creation succeeded but publishing failed, the pending finish records that progress. Retry the pending Finish & Push to continue publishing without repeating completed merges or recreating the tag. A remote branch that has moved still needs review and reconciliation; retrying does not authorize a force push. If you resolved or abandoned the operation manually, inspect Git Graph, then use Clear pending finish… to remove its saved progress record. Clearing that record keeps the branches, commits and tags; it neither pushes nor undoes the operation. For simultaneous tasks that should not share files, use worktrees.

Related guides: worktrees, automatic commit conditions.

Source Control and history controls#

A diff is a comparison, staging is a selection, a commit is a local history record, and a push publishes commits. For a safe first manual commit, stage one intended file, read the staged diff, write a specific message and check History afterward. Review automatic commits before enabling them.