How to Use Version Control#

Overview#

This guide explains how to use the Git versioning features in the Desktop App.

The Desktop App has a limited set of managed Git features that enable end-to-end versioning.

They are for convenience and ensuring reprodubility. They do not provide command line level control for Git. If you need that, use Git natively or in a client.

You don’t need to know anything about Git in the terminal to use the Desktop App features.

They are self contained and provide a simple on-ramp to more complex version control.

If you already work with Git, they will simplify a few situations for you.

Key Concepts#

Commit: A snapshot of your project at a specific point in time. The act of creating the snapshot which captures changes in the index.
Index: Set of “staged” file changes selected to be committed. Can be different from the working state of a file in the repository if you’ve edited the file after staging it.
Branch: An independent line of development within your project. Captured in a commit history.
Merge (conflict/clean): Git operation that adds changes from branch ‘B’ into branch ‘A’: ‘B’ –> ‘A’. Will fail and prompt conflict resolution if ‘A’ and ‘B’ have competing changes to a common file, ‘f’. Called clean if ‘A’ and ‘B’ have no such conflicts.
My changes vs Their changes: Frames conflicting changes to common file ‘f’ in terms of branch ‘A’ vs ‘B’. “My changes” are changes to ‘f’ in ‘A’. “Their changes”” are changes to ‘f’ in ‘B’.
Remote Repository: A version of your project hosted on a Git server (GitHub, GitLab, etc.).

Commit Changes#

Step One: View and select changes to commit in the Changes Screen.

Select Project Tab > Git > Changes
Review file changes by selecting the corresponding row
Uncheck any file changes you do not want to commit

Step Two: Commit the changes and review/edit the commit message.

Select Commit Top (LHS)
Review and edit the autogenerated commit message in the Create a commit modal
Select Create a commit > Commit

Success: Changes page shows “You’re up to date!”.

Committing in the Desktop App commits all selected changes, regardless of your index.

Committing in the Desktop App will stage and commit all changes selected in Git > Changes. It ignores anything you’ve staged in the terminal.

Create a Branch#

Step One: Create a new branch in the Branch Short Cut.

Select Branch Short Cut (Top RHS) > Create Branch

Step Two: Enter a branch name and create it.

Enter Create Branch > Branch Name
Select Create Branch > Create Branch

Success: The new branch becomes the active branch in the Branch Shortcut.

Switch Branches#

Select the target branch in the Branch Short Cut.

Select Branch Shortcut (Top RHS) > branch name

Success: The target branch becomes active and the name shows in the Branch Shortcut.

You can only switch branches if the current branch has no changes to commit.

Switching will be blocked if the curreent branch has changes to commit. You must commit or discard them first. You can also stash them in the terminal and then switch.

Merge Branches#

Do this when you have changes in branch ‘B’ that you want to bring into branch ‘A’.

The most typical situation is when ‘B’ is a “feature branch”, and ‘A’ is the main branch.

Step One: Switch to the branch you want to merge changes INTO, call it ‘A’.

Select Branch Shortcut (Top RHS) > branch name

Step Two: Initiate the merge in the Branch Screen.

Select Git > Branches > Merge Branch

Step Three: Select the branch to merge FROM in the Merge Branch modal, call it ‘B’.

Select Merge Branch > ‘B’
Select Merge Branch > Merge Branch

Success: If there are no conflicts the merge will pass.

If there are conflicting changes, the merge will not be accepted.

You will be prompted to resolve the conflicts within the Merge Conflicts modal.

Resolve Merge Conflicts#

The Merge Conflicts modal will open if there are conflicts merging ‘B’ into ‘A’.

You must resolve conflicts on a file-by-file basis. Individual files may have multiple conflicts. The modal stays open until you resolve the conflicts or you abort the merge.

Merge Conflicts modal provides four resolution options.

Resolve using ‘My Changes’: Use the entire file ‘f’ in ‘A’ and accept no changes from ‘B’
Resolve using ‘Their Changes’: Do the opposite and use the entire file ‘f’ from ‘B’
Launch VS Code: Launch VS Code to combine changes from ‘A’ and ‘B’
Launch Default Editor: Launch a local file editor to combine changes from ‘A’ and ‘B’

Resolve conflicts: Resolve the conflicts on a file-by-file basis in the Merge Conflicts modal.

Select a file and resolution method in Merge Conflicts > File Card
Repeat until all conflicts are resolved
Select Merge Conflicts > Commit Merge

Abort merge: You can abort the merge and abandon your resolutions at anytime.

Select Merge Conflicts > Abort Merge > Confirm Abort Merge

Success: The merge completes and a merge commit appears in History.

The VS Code and Default Editor resolution methods depend on a few things.

The VS Code option requires VS Code to be configured in the project
The Default Editor option is only presented if the project is local

You do not need to resolve the conflicts through the Merge Conflict modal.

Resolve the conflicts directly in the files with any file editor with access to the files.

Push Changes#

You can push changes back to the remote repository through the Publish feature.

The Publish feature converts to a Fetch/Pull/Push feature if the project is on a remote.

Step One: Commit changes locally.

Review and manage changes in Project Tab > Git > Changes
Select Commit

Step Two: Push the changes.

Select Push

Success: Push Successful modal will show.

You may be required to fetch and then pull changes from the remote before you push.

If there are conflicts, this will trigger a merge conflict resolution.

Fetch/Pull Updates#

You can fetch/pull changes back from the remote through the Publish feature.

The Publish feature converts to a Fetch/Pull/Push feature if the project is on a remote.

Step One: Fetch the changes locally.

Select Fetch

Step Two: Pull the changes.

Select Pull

Success: Pull Successful modal will show.

Pulling changes may trigger a merge conflict resolution.

You will need to resolve any conflicting changes prior to completing the pull.

Delete a Branch#

You can delete a branch in the Project Tab > Branches page.

However, you must delete it from another branch. You cannot delete an active branch.

Select Project Tab > Git > Branches
For the branch you want to delete, select Option Dots > Delete Branch
Select Delete Branch > Delete Branch

Success: The branch disappears from the Branches page.

The Desktop App Delete feature requires committing and pushing the branch prior to deletion.

This is a safeguard against deleting desired work. Bypass it by hard deleting the branch in a terminal line with git branch -D <BRANCH_NAME>.