Adding an Existing Project to GitHub Desktop 📁

Got a folder with code on your computer and want to start using Git? Here’s how to add a local project to GitHub Desktop.

When Do You Need This?

• You have a folder with code that isn’t a Git repository yet
• You cloned a project through the terminal and want to open it in a GUI
• You received an archive of a project from a colleague
• You were working on a project without Git and decided to start versioning

Option 1: Add an Existing Git Repository

If the folder is already a Git repository (has a .git folder):

Steps:

1. Open GitHub Desktop
2. File → Add Local Repository
3. Click Choose… and select the folder
4. Click Add Repository

✅ Done! The repository appears in GitHub Desktop.

What you’ll see:

• Commit history in the History tab
• Current changes in Changes (if any)
• Current branch in the header

Option 2: Initialize a New Repository

If the folder is not a Git repository:

Steps:

1. File → Add Local Repository
2. Select the folder with your project
3. You’ll see an error: “This directory does not appear to be a Git repository”
4. Click Initialize Git Repository or create a repository

GitHub Desktop will create a .git folder automatically!

After initialization:

1. All files appear in Changes (untracked)
2. Make the first commit:
   - Summary: Initial commit
   - Click Commit to main

Option 3: Create a New Repository from Scratch

If the project doesn’t exist yet:

Steps:

1. File → New Repository
2. Fill in:
   - Name: project name
   - Description: brief description
   - Local Path: where to create it
   - ✅ Initialize this repository with a README
   - Git Ignore: choose a template (Python, Node, Java…)
   - License: choose a license (optional)
3. Create Repository

GitHub Desktop will create the folder and initialize Git!

Understanding the GitHub Desktop Interface

Left panel: Changes

Shows modified files:

✓ new_file.py        (green +)
✓ modified.js        (yellow dot)
✓ deleted.txt        (red -)

Checkboxes — files that will be included in the commit.
Uncheck a file to exclude it from the commit.

Right panel: Diff

Shows exactly what changed:

function hello() {
-  console.log("Hello");
+  console.log("Hello World!");
}

• Red lines (- minus) — removed
• Green lines (+ plus) — added

Bottom section: Commit

Two fields:

1. Summary — short description (required)
2. Description — details (optional)

Common Tasks

Open project in editor

1. Repository → Open in Visual Studio Code (or another editor)
2. Or: Ctrl+Shift+A (Windows) / Cmd+Shift+A (Mac)

Open folder in file explorer

1. Repository → Show in Explorer (Windows)
2. Or: Repository → Show in Finder (Mac)
3. Or: Ctrl+Shift+F / Cmd+Shift+F

Open terminal in project folder

1. Repository → Open in Terminal
2. Or: Ctrl+** (Windows) / **Cmd+ (Mac)

Setting Up .gitignore

After adding a project you’ll often need to configure .gitignore:

What is it?

The .gitignore file tells Git which files NOT to track:

• Dependencies (node_modules/, venv/)
• Builds (dist/, build/, *.pyc)
• Configs (.env, .idea/, .vscode/)
• System files (.DS_Store, Thumbs.db)

How to add:

1. Repository → Repository Settings → Ignored Files
2. Or create a .gitignore file in the project root

Template examples:

Python:

__pycache__/
*.py[cod]
venv/
.env

Node.js:

node_modules/
.npm
.env
dist/

General:

.DS_Store
.idea/
.vscode/
*.log

Troubleshooting

“This directory appears to be a Git repository”

The folder is already a Git repository! Just:
- File → Add Local Repository (don’t create a new one!)

“The repository is missing or not accessible”

Check:
- Is the path correct?
- Do you have access rights to the folder?
- Did you delete the .git folder?

Too many untracked files

Set up .gitignore before the first commit:

1. Add .gitignore with the necessary patterns
2. Remove unwanted files from Changes
3. Make a commit

Example: Adding a Python Project

# You have a project
my-python-app/
├── app.py
├── requirements.txt
└── venv/              # NOT needed in Git!

Steps:

1. Open GitHub Desktop
2. File → Add Local Repository
3. Select my-python-app/
4. Click create a repository
5. Create .gitignore:
   venv/ __pycache__/ *.pyc .env
6. Only app.py and requirements.txt remain in Changes
7. Make a commit: Initial commit

✅ Done! Project is under Git!

What’s Next?

After adding the project:

1. ✅ Publish on GitHub (Publish repository)
2. ✅ Set up .gitignore
3. ✅ Make commits when changes happen
4. ✅ Create branches for new features

Your project is now safely under Git! 🚀