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

GitHub doesn't work quite like your desktop file manager. You can't simply right-click and create a new empty folder — and understanding why changes how you approach organizing your repositories entirely.

Why GitHub Doesn't Support Empty Folders

Git, the version control system that powers GitHub, tracks files — not directories. A folder with nothing in it is invisible to Git. This is a fundamental design decision, not a bug or oversight. It means that before you can add a folder to a GitHub repository, you need at least one file inside it.

This trips up a lot of new users who expect folder creation to work the way it does in Google Drive or Windows Explorer. Once you understand the file-first logic, the workarounds become obvious.

Method 1: Adding a Folder Through the GitHub Web Interface

The simplest approach for most users — no command line required.

1. Navigate to your repository on github.com
2. Click "Add file" → "Create new file"
3. In the filename field, type your folder name followed by a forward slash (e.g., my-folder/)
4. GitHub will automatically recognize this as a directory and drop your cursor into a new filename field
5. Enter a filename (e.g., README.md or .gitkeep)
6. Add some content, or leave a placeholder note
7. Scroll down and commit the new file

The folder appears in your repository the moment the file is committed. The slash is the key — typing it signals to GitHub's interface that you're defining a path, not just a filename.

What to Put in a Placeholder File

If you're creating a folder purely for structure and don't have real content yet, a common convention is to add a file called .gitkeep. This is an empty file (or nearly empty) that exists solely to make Git acknowledge the directory. It's not an official Git feature — just a widely adopted community practice. Some developers prefer README.md with a brief description of what the folder will contain, which adds useful context for collaborators.

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

If you're working locally and pushing to GitHub, the process is straightforward:

mkdir my-new-folder touch my-new-folder/.gitkeep git add my-new-folder/.gitkeep git commit -m "Add my-new-folder directory" git push origin main 

mkdir creates the directory locally. touch creates an empty file inside it. Without that file, git add won't pick up the folder at all — you can confirm this by running git status before and after adding the placeholder.

This method is typically faster once you're comfortable with the terminal, especially when creating multiple nested folders at once.

Method 3: Adding a Folder by Uploading Files

If you already have files to add, you can drag and drop them into GitHub's web interface:

1. Open your repository
2. Click "Add file" → "Upload files"
3. Drag a folder from your computer into the upload area

GitHub will preserve the folder structure from your upload. This works well for adding entire project directories at once. Keep in mind that browser-based uploads can be unreliable for very large folders — the command line or a Git client like GitHub Desktop handles those more reliably.

Nested Folders and Deeper Directory Structures

Creating subfolders follows the same logic. In the web interface, you can define a full path in one step:

src/components/ui/Button.jsx 

Typing that entire path in the filename field — with each / acting as a directory separator — creates all three levels of nesting simultaneously. GitHub builds the folder hierarchy around the file you're committing.

On the command line, you can achieve the same with:

mkdir -p src/components/ui 

The -p flag creates parent directories as needed, so you don't have to create each level one at a time.

Variables That Affect How You'll Approach This 📁

The right method depends on several factors that vary by user:

Someone maintaining a solo project might handle everything through the GitHub web interface without any friction. A developer working within a team repository with protected branches and required pull requests will need to follow a different process — creating a branch, adding the folder locally, and opening a PR rather than committing directly.

When Folder Structure Actually Matters

For small or personal repositories, folder organization can feel optional. As projects grow, consistent directory structure becomes important for discoverability, automation, and collaboration. Many frameworks and tools expect files to live in specific directories — placing source code in src/, tests in tests/, or configuration in config/ isn't just convention in those cases, it's a functional requirement.

If you're organizing a repository for others to use or contribute to, the placeholder file you choose and how you name your directories communicates a lot about project maturity and intent. What makes sense depends entirely on how your project is structured, who else is working in it, and what tooling you're building around it.