How to Add a Folder in GitHub: What You Need to Know

GitHub doesn't work quite like a regular file system — and that trips up a lot of people the first time they try to create a folder. The short version: GitHub doesn't track empty folders. A folder only exists in a repository if it contains at least one file. Once you understand that constraint, the process becomes straightforward across every method available.

Why GitHub Handles Folders Differently

Git — the version control system that powers GitHub — tracks file content, not directory structure for its own sake. Folders are inferred from file paths. If you have a file at src/components/Button.js, Git recognizes src/ and components/ as directories automatically. Remove all files from those directories, and the folders disappear from the repository entirely.

This is by design, not a bug. It keeps repositories lean and focused on actual content. But it does mean your approach to adding folders depends on your workflow and tools.

Method 1: Adding a Folder Through the GitHub Web Interface

The browser-based editor is the most accessible option, especially for users who don't have Git installed locally.

Steps:

1. Navigate to your repository on GitHub.com
2. Click "Add file" → "Create new file"
3. In the filename field at the top, type your folder name followed by a forward slash — for example: docs/
4. GitHub will automatically recognize this as a directory and move your cursor into a new filename field inside that folder
5. Type a filename — commonly README.md or .gitkeep — to satisfy the requirement that the folder contains at least one file
6. Add content to the file (even a single line or space works)
7. Scroll down and click "Commit changes"

The folder now exists in your repository. The key trick is the forward slash in the filename field — that's what signals to GitHub that you're declaring a directory path, not just a filename.

Method 2: Adding a Folder via Git on the Command Line 🖥️

If you're working locally with Git installed, this is the most flexible and scalable approach.

Steps:

1. Open your terminal and navigate to your local repository
2. Create the folder: mkdir your-folder-name
3. Add a placeholder file inside it: touch your-folder-name/.gitkeep
4. Stage the new file: git add your-folder-name/.gitkeep
5. Commit the change: git commit -m "Add your-folder-name directory"
6. Push to GitHub: git push origin main (replace main with your branch name if different)

What is .gitkeep? It's a naming convention — not a special Git feature. It's simply an empty file used as a placeholder to make an otherwise-empty directory trackable. Some teams use .gitignore inside the folder instead, since that file also serves a functional purpose.

Method 3: Using GitHub Desktop

GitHub Desktop offers a middle ground — a graphical interface that works with your local file system.

Steps:

1. Open your repository in GitHub Desktop
2. Use your operating system's file explorer or Finder to create a new folder inside the local repo directory
3. Add at least one file to that folder
4. Return to GitHub Desktop — the new folder and file will appear under "Changes"
5. Write a commit summary and click "Commit to main"
6. Click "Push origin" to sync to GitHub

This method gives you full control over folder structure using familiar OS tools, while GitHub Desktop handles the Git mechanics.

Method 4: Using a Code Editor with Git Integration

Editors like VS Code, JetBrains IDEs, or Sublime Text with Git plugins let you create folders directly from the editor's file tree. The Git integration stages and commits changes without leaving the editor environment. The same rule applies — the folder needs at least one file before it will appear in a commit.

Variables That Affect Which Method Works Best

Nested Folders and Deeper Structures

You can create multiple levels of nesting in a single step. In the web interface, typing src/components/buttons/ in the filename field creates three directories at once, provided you add a file at the deepest level. On the command line, mkdir -p src/components/buttons creates the full path in one command (-p creates intermediate directories as needed).

Common Mistakes to Avoid

Trying to commit an empty folder — Git will simply ignore it. Always include at least one file.

Using spaces in folder names — Technically allowed, but spaces in directory paths can cause friction with command-line tools. Hyphens (my-folder) or underscores (my_folder) are safer conventions.

Forgetting to push — A commit lives locally until you push it. After committing, always verify the folder appears on GitHub.com if that's where it needs to be. 📁

Working on the wrong branch — Check which branch you're on before committing, especially in repositories with protected main branches or active pull request workflows.

The Piece That Varies by Setup

The mechanics above are consistent, but which method fits your situation depends on factors only you can assess — whether your team uses branch protection, how comfortable you are with the command line, what editor you're already using, and how your repository is structured. Some workflows make the web interface the obvious choice; others make local Git commands more practical. The underlying behavior of Git — requiring at least one file per folder — stays constant regardless of the path you take to get there.