How to Create a Folder in a GitHub Repository: Step-by-Step Guide to Adding Files

TutorialPedia Team

Date Updated

GitHub has become the cornerstone of collaborative software development, enabling millions to store, share, and version-control code. A well-organized repository (repo) is key to maintaining clarity, especially as projects grow. Folders (directories) help group related files—like docs/ for documentation, src/ for source code, or assets/ for images—making it easier for collaborators (and future you) to navigate.

But here’s a quirk: GitHub’s web interface doesn’t have a direct "Create Folder" button. Instead, folders are created indirectly by adding files with a specific path. Don’t worry—this guide will walk you through multiple methods to create folders in GitHub: using the web interface (for beginners) and the command line (for power users). By the end, you’ll also learn how to add files to your new folder and troubleshoot common issues.

Table of Contents#

  1. Prerequisites
  2. Why Organizing with Folders Matters
  3. Method 1: Creating a Folder via GitHub’s Web Interface
  4. Method 2: Creating a Folder via the Command Line (Git)
  5. Adding Files to Your New Folder
  6. Common Issues & Troubleshooting
  7. Conclusion
  8. References

Prerequisites#

Before starting, ensure you have:

  • A GitHub account (free or paid).
  • An existing GitHub repository (or create a new one by following these steps).
  • Basic familiarity with GitHub terms (e.g., "repository," "commit," "branch").

For the command line method, you’ll also need:

Why Organizing with Folders Matters#

Folders (directories) transform chaotic repositories into structured, navigable spaces. Benefits include:

  • Clarity: Team members can quickly find files (e.g., tests/ for test scripts, examples/ for demos).
  • Scalability: As projects grow, folders prevent a "flat" structure where hundreds of files clutter the root.
  • Collaboration: Consistent folder structures (e.g., src/, docs/) align team workflows.

Method 1: Creating a Folder via GitHub’s Web Interface#

The GitHub web interface is beginner-friendly and requires no local setup. Since GitHub doesn’t support empty folders, we’ll create a folder and a file in one step. There are three ways to create folders using the web interface:

Option A: Creating a File with Folder Path#

This is the most common method, where you create a file and specify its folder path.

Step 1: Navigate to Your Repository#

  1. Log in to GitHub.
  2. On your homepage, click the repository where you want to create the folder (e.g., my-project).

Step 2: Initiate File Creation#

  1. In the top-right corner of the repository page, click the green "Add file" button.
  2. From the dropdown menu, select "Create new file".

Step 3: Define the Folder Structure#

In the "Name your file…" field, enter your folder name followed by a / (slash) and a filename. The slash tells GitHub to create the folder and place the file inside it.

Example: To create a folder named docs with a file README.md, type:

docs/README.md

Note: In the GitHub interface, type "docs/README.md" in the filename field to create a docs folder with a README.md file inside.

Step 4: Add Content to the File#

GitHub requires file content to save. For placeholder text, you can type:

# Documentation Folder  
This folder contains project documentation.

Step 5: Commit the Changes#

  1. Scroll to the bottom of the page. In the "Commit new file" section:
    • Add a descriptive commit message (e.g., "Create docs folder with README").
    • Choose to commit directly to the main branch (default) or create a new branch (recommended for collaborative projects to avoid breaking main).
  2. Click "Commit new file".

Result#

You’ll now see the docs folder in your repository. Click it to view the README.md file inside!

Option B: Modifying the Upload URL#

This method allows you to create new directories by modifying the URL when uploading files.

Step 1: Navigate to Upload Page#

  1. Go to your repository on GitHub.
  2. Click "Add file" > "Upload files".
  3. Look at the URL in your browser. It will look something like: 
    https://github.com/username/repository/upload/main

Step 2: Modify the URL#

Add the desired directory path to the end of the URL:

https://github.com/username/repository/upload/main/new-folder/subfolder

Step 3: Upload Files#

  1. Drag and drop files into the upload area, or click to select files.
  2. Add a commit message.
  3. Click "Commit changes".

This creates the new directories (new-folder/subfolder/) and uploads your files in one step.

Option C: Drag and Drop Folders#

The easiest method is to drag entire folders directly into the GitHub web interface.

Step 1: Navigate to Target Location#

  1. Go to your repository on GitHub.
  2. Navigate to the parent directory where you want to create the new folder.

Step 2: Drag and Drop#

  1. Open your file manager (Windows Explorer, Finder, etc.).
  2. Select the folder you want to upload.
  3. Drag it into the GitHub web interface's file area.

Step 3: Commit#

  1. Add a commit message.
  2. Click "Commit changes".

Note: The folder cannot be empty, and text files inside must contain some content.

Method 2: Creating a Folder via the Command Line (Git)#

For developers comfortable with terminal commands, the Git CLI (command line interface) offers more control.

Why Git Doesn't Track Empty Folders#

Git is a content-addressable filesystem that tracks files, not directories. A directory only exists in Git implicitly through its contents. If a directory has no files, Git has nothing to store. This isn't a bug—it's by design. The official Git FAQ states: "Currently the design of the Git index (staging area) only permits files to be listed."

Step 1: Clone the Repository (If Not Local)#

If the repository isn’t on your computer, clone it first:

git clone https://github.com/your-username/your-repo.git

Replace your-username and your-repo with your GitHub username and repository name.

Step 2: Navigate to the Repository Directory#

Use cd (change directory) to enter the cloned repo:

cd your-repo

Step 3: Create the Folder#

Use mkdir (make directory) to create your folder. For example, to create a src folder:

mkdir src

Step 4: Add a File to the Folder (Critical!)#

Git ignores empty folders. To track the src folder, add a file inside it. You have several options:

Option 1: Create a meaningful file (e.g., index.js, README.md):

touch src/index.js

Option 2: Use a placeholder file for empty directories that will contain tracked files later:

touch src/.gitkeep

The .gitkeep file is a community convention—Git doesn't recognize it specially, but it signals that the file exists solely to keep the directory. Alternatively, you can use .keep or any other filename.

Option 3: Use .gitignore as a placeholder (recommended by Git FAQ) when you want the directory to exist but its contents ignored:

cat > src/.gitignore << 'EOF'
# Ignore everything in this directory
*
# Except this .gitignore file
!.gitignore
EOF

Step 5: Stage, Commit, and Push Changes#

  1. Stage the new folder and file:

    git add src/

    (The / ensures Git tracks the entire folder.)

  2. Commit the changes with a message:

    git commit -m "Create src folder with index.js"

  3. Push the changes to GitHub:

    git push origin main

    (Replace main with your branch name if using a custom branch.)

Result#

Check your GitHub repository in the browser. The src folder will appear with index.js inside!

Adding Files to Your New Folder#

Once your folder exists, add more files using either method:

Via Web Interface#

  1. Navigate to the folder (e.g., docs).
  2. Click "Add file" > "Upload files" (to upload from your computer) or "Create new file" (to write text directly).

Via Command Line#

  1. Copy files into the folder (e.g., drag guide.pdf into docs/ on your computer).
  2. Stage, commit, and push: 
    git add docs/guide.pdf  
git commit -m "Add guide.pdf to docs folder"  
git push origin main

Common Issues & Troubleshooting#

Issue 1: Folder Doesn’t Appear on GitHub#

Why? Git doesn’t track empty folders. If you created a folder but no files, it won’t show up.
Fix: Add a file to the folder (e.g., placeholder.txt or README.md), then commit and push.

Issue 2: "Permission Denied" Error (Command Line)#

Why? You lack write access to the repository (e.g., it’s private and you’re not a collaborator).
Fix: Ask the repo owner to add you as a collaborator (via "Settings" > "Manage access").

Issue 3: Folder Created in the Wrong Path#

Why? Typos in the filename path (web) or cd command (CLI).
Fix (Web): Delete the misnamed folder by deleting its files (GitHub removes empty folders automatically). Recreate with the correct path.
Fix (CLI): Use rm -r wrong-folder-name to delete the folder, then retry with the correct name.

Conclusion#

Organizing your GitHub repository with folders is a foundational skill for clean, scalable projects. Use the web interface for quick, browser-based folder creation (great for beginners), or the Git CLI for advanced control (ideal for local development workflows).

Remember: GitHub/Git requires at least one file per folder to track it. With these steps, you’ll keep your codebase organized and collaboration seamless!

References#

2025-12