These Tech Guides and instructions are provided in good faith as a general educational guide. Technology changes over time, and settings, software versions, menu names, and features may vary by system and GitHub Desktop version.
I cannot guarantee that these steps will work in every environment, and I am not responsible for data loss, configuration problems, system errors, security issues, or other problems that may result from following this guide.
Never commit passwords, API keys, personal access tokens, or other secrets to a repository.
Anything you push to a public repository can be seen by anyone on the internet.
Back up important work before discarding changes or deleting repositories.
When in doubt, consult the official GitHub documentation.
Overview
GitHub Desktop is a free app from GitHub that lets you work with Git repositories through buttons and menus instead of typing Git commands. You can clone a repository from GitHub to your computer, see exactly what changed in your files, commit those changes, and push them back to GitHub.
This guide shows how to install GitHub Desktop on Windows or Mac, sign in to your GitHub account, and then clone a repository, commit a change, and push it to GitHub. It also shows how to create a new repository and publish it.
Main idea: GitHub Desktop is a visual front end for Git that is connected to your GitHub account. You make changes in your own editor, and GitHub Desktop handles the commit, push, and pull steps.
Requirements
A computer running Windows 10 (64-bit) or later, or macOS 12 or later. GitHub Desktop does not officially support Linux.
A free GitHub account. See the GitHub guide if you need to create one.
A web browser, which GitHub Desktop uses for signing in.
GitHub Desktop includes its own copy of Git, so you do not need to install Git separately to use it. See the Git guide if you also want Git at the command line.
You sign in through your web browser. GitHub Desktop does not accept your username and password directly.
Some menu names differ between Windows and Mac. This guide notes both.
Key Terms
GitHub Desktop's buttons are named after Git actions. Knowing these terms makes the app much easier to follow:
Term
Meaning
Repository (repo)
A project folder whose history Git tracks.
Clone
Copy a repository from GitHub to your computer, keeping the connection so you can push and pull.
Commit
Save a snapshot of your changes in your local repository, with a short message describing them.
Push
Send your local commits up to GitHub.
Fetch
Check GitHub for new commits without changing your files.
Pull
Download new commits from GitHub and update your local files.
Origin
The name Git uses for the GitHub copy of your repository.
Branch
A separate line of work. New repositories start on a branch named main.
GitHub Desktop Instructions
Work through the tabs in order. Each tab builds on the one before it, and most end with a Check yourself note.
Getting Started with GitHub Desktop
Click the tabs above in order. You need about 30 minutes and your GitHub username and password.
Click Download for Windows or Download for macOS. The site usually detects your operating system for you.
The installer saves to your Downloads folder.
Install on Windows
Double-click the GitHubDesktopSetup file in your Downloads folder.
The installer runs on its own; there are no options to choose. GitHub Desktop opens when it finishes.
Later, you can start it from the Start menu by searching for GitHub Desktop.
Install on Mac
Double-click the downloaded GitHub Desktop.zip file to unzip it.
Drag the GitHub Desktop app into your Applications folder.
Double-click it to open it. If macOS asks whether you are sure you want to open an app downloaded from the internet, click Open.
Check yourself: GitHub Desktop opens and shows a Welcome to GitHub Desktop screen.
Part 2: Sign In and Configure Git
The first time GitHub Desktop opens, it walks you through signing in and setting your Git name and email. If you skipped that, use the steps below.
Sign In to GitHub.com
On the welcome screen, click Sign in to GitHub.com. If you skipped the welcome screen, open settings (File → Options on Windows, GitHub Desktop → Settings on Mac), choose Accounts, and click Sign into GitHub.com.
Use Sign into GitHub.com, not Sign into GitHub Enterprise. Enterprise is only for organizations with their own GitHub servers.
In the Sign in using your browser window, click Continue with browser. Your default browser opens.
Sign in to GitHub in the browser. If you use two-factor authentication, enter your code and click Verify.
If GitHub asks you to authorize GitHub Desktop, click Authorize desktop.
If your browser asks whether to open GitHub Desktop, allow it. You return to the app, signed in.
Set Your Git Name and Email
Git attaches a name and email to every commit you make. GitHub Desktop offers to fill these in from your GitHub account.
On the Configure Git screen, choose Use my GitHub account name and email address, or enter them yourself, and click Finish.
To change them later, open settings and choose Git.
Note: The email in your Git settings appears in the history of every repository you push to. If you want to keep your email private, use the noreply email address GitHub provides in your GitHub account's email settings.
Check yourself: In settings, the Accounts section shows your GitHub username and avatar.
Part 3: Clone a Repository from GitHub
Cloning copies a repository from your GitHub account to your computer. If you don't have a repository yet, create one on GitHub first (see the GitHub guide), or skip to 5. New Repository.
Choose File → Clone repository. If you are on the start screen, you can also click Clone a repository from the Internet.
Click the GitHub.com tab. Your repositories are listed, including ones shared with you.
Select the repository you want. Type in the filter box to find it quickly.
Check the Local path. By default it is a folder inside Documents\GitHub (Windows) or Documents/GitHub (Mac). Click Choose… to pick a different location.
Click Clone. GitHub Desktop downloads the repository.
To clone a repository that isn't in your list, such as a classmate's or a public project, click the URL tab and paste the repository's web address, for example https://github.com/owner/repository.
When the clone finishes, the main window shows:
Current repository (top left): the repository you are working in. Click it to switch repositories.
Current branch (top middle): usually main.
Fetch origin (top right): checks GitHub for changes. This button changes to Pull origin or Push origin when there is something to pull or push.
Changes and History tabs (left side).
Check yourself: Click Show in Explorer (Windows) or Show in Finder (Mac), or choose Repository → Show in Explorer/Finder. The folder opens and contains the repository's files.
Part 4: Commit and Push a Change
You edit files with any app you like. GitHub Desktop notices the changes and lets you commit and push them.
Make a Change
Open the repository folder (Repository → Show in Explorer/Finder), or open it in your editor with Repository → Open in Visual Studio Code (or your configured editor).
Edit a file, such as README.md, or add a new file, then save it.
Commit the Change
Return to GitHub Desktop and open the Changes tab. Each changed file is listed with a checkbox, and the right side shows the exact lines added (green) and removed (red).
Make sure the files you want to include are checked.
At the bottom left, type a short Summary of the change, for example Update README with project description. The Description box is optional.
Click Commit to main. The commit is saved in your local repository only.
Push to GitHub
The top-right button now reads Push origin, with a count of commits waiting to be pushed.
Click Push origin. Your commit is uploaded to GitHub.
To confirm, choose Repository → View on GitHub. Your change appears on the repository page.
Pull Changes Made Elsewhere
If the repository changes on GitHub, for example a collaborator pushes a commit or you edit a file on GitHub.com or another computer, bring those changes down before you start working:
Click Fetch origin. If there are new commits, the button changes to Pull origin.
Click Pull origin to update your local files.
Open the History tab to see every commit, newest first.
Note: A good habit is pull before you start, push when you finish. Working from an out-of-date copy is the most common cause of conflicts.
Check yourself: Your commit appears in the History tab, and the change is visible on the repository's page on GitHub.com.
Part 5: Create and Publish a New Repository
You can also start a project on your computer and then publish it to GitHub.
Choose File → New repository.
Enter a Name and an optional Description, and choose the Local path.
Check Initialize this repository with a README. Optionally choose a Git ignore template for your language, such as Python or Java, so temporary files aren't committed.
Click Create repository. The repository now exists on your computer only.
Click Publish repository at the top right.
Keep Keep this code private checked unless you want the repository to be public, then click Publish repository.
Check yourself: Choose Repository → View on GitHub. The new repository opens on GitHub.com with your README file.
Adding an Existing Folder
If you already have a project folder, choose File → Add local repository and select the folder.
If the folder isn't a Git repository yet, GitHub Desktop offers to create a repository there. Then publish it as above.
Next Steps
Learn more about Git and how it differs from GitHub in the Git guide.
Learn to invite collaborators, download files, and create personal access tokens in the GitHub guide.
Try creating a branch with Branch → New branch, making a commit on it, and opening a pull request with Branch → Create pull request.
