Skip to main content

Branches with GitHub Desktop

This guide explains how to use GitHub Desktop to work on a separate branch, save your changes (commit), and upload them to GitHub (push). It assumes the repository is already cloned on your computer.

Before you start​

  • GitHub Desktop is installed and you are signed in.
  • You have cloned this docs repository ( File → Clone repository if you have not yet).
  • You know which default branch the team uses (often main or master). This guide uses main; if yours is different, pick that branch instead.

1. Create a new branch​

  1. Open GitHub Desktop and select this repository in the list (top left).
  2. Check the current branch name in the branch dropdown (toolbar). Usually you start from main.
  3. Click Current branch → New branch… (or Branch → New branch from the menu).
  4. Enter a short, descriptive branch name in English, using hyphens, for example:
    • docs-vps-backup-page
    • fix-navbar-link
  5. Under Create branch based on…, choose main (or your team’s default branch).
  6. Click Create branch.

You are now on your new branch. Any new commits will go here, not directly on main.

2. Edit files and save on disk​

  1. Open the project folder in your editor ( Repository → Show in Explorer / Reveal in Finder, then open the folder in VS Code or any editor).
  2. Change or add files (for example under docs/).
  3. Save each file (Ctrl+S / Cmd+S).

GitHub Desktop watches the folder. After you save, changed files appear in the Changes tab.

3. Commit your changes (save a snapshot in Git)​

A commit is a saved snapshot of your work with a message.

  1. In GitHub Desktop, open the Changes tab (left side).
  2. Review the list of changed files. Uncheck any file you do not want in this commit (rare for docs work).
  3. At the bottom left, fill in:
    • Summary (required): one short line, e.g. Add VPS backup doc or Fix typo in intro.
    • Description (optional): more detail if needed.
  4. Click Commit to … (the button label includes your current branch name).

Your changes are now recorded locally on that branch. They are not on GitHub yet until you push.

Good commit messages

Use the imperative mood and keep the summary under about 50 characters when possible, for example: Add guide for GitHub Desktop, not Added or Adding.

4. Push your branch to GitHub​

  1. After at least one commit, look at the top toolbar. If you see Publish branch, your branch exists only on your PC—click Publish branch to create it on GitHub and upload your commits.
  2. If you already published this branch before and made new commits, click Push origin instead (or Repository → Push).

When the push finishes, your branch and commits are on GitHub. Others can see the branch in the repo on the website.

5. (Optional) Open a pull request​

When your work is ready for review:

  1. In GitHub Desktop, click Branch → Create pull request on GitHub (or use the banner if shown).
  2. On GitHub.com, set base to main (or your team default) and compare to your branch.
  3. Add a title and description, then Create pull request.

Your team can review, request changes, and merge when ready.

Quick recap​

StepWhat to do in GitHub Desktop
New branchCurrent branch → New branch… from main
Save workEdit files, save in the editor
CommitChanges tab → summary → Commit to …
UploadPublish branch (first time) or Push origin

If something looks wrong​

  • Wrong branch? Use Current branch and select the branch you want before committing.
  • No changes listed? Save the file again; confirm you are in the correct repository folder.
  • Push rejected? Someone else may have updated the remote. Use Fetch origin, then follow your team’s process (sometimes Pull with rebase or merge). Ask the tech lead if you are unsure.

For official help, see GitHub Desktop documentation.