You Just Cloned Your First Repository, Now What?
You’ve set up your GitHub account, forked a project, or maybe you’re starting your own. The code is there, but it’s a flat list of files staring back at you. You know you need structure—a place for images, a separate folder for documentation, another for source code. The instinct is to right-click and select “New Folder,” but GitHub’s web interface doesn’t work like your desktop file explorer.
This moment of confusion is incredibly common. The platform is built around Git, a version control system that tracks changes to files, not directories themselves. An empty folder is invisible to Git. This fundamental concept is why the process isn’t intuitive at first glance. Let’s demystify it and give you the clear, actionable methods to organize your repository with folders, directly from your browser or command line.
Understanding the GitHub and Git Folder Paradox
Before diving into the steps, it’s crucial to understand why you can’t just create an empty folder. Git, the engine behind GitHub, is designed to track content. It saves snapshots of your files. A folder, by itself, has no content—it’s just a path or a directory entry in your operating system.
Think of it like a filing cabinet. Git only cares about the documents inside the drawers. If you add a new, empty drawer, Git doesn’t see anything to track. To make Git acknowledge the drawer, you must place at least one file inside it. This is the golden rule: in Git, folders exist implicitly because of the files within them.
This design keeps the repository lean and focused on what actually matters: your code and assets. Once you internalize this, the methods for creating folders become logical. You’re not really “creating a folder” in the traditional sense; you’re creating a file within a new directory path, and Git brings that directory into existence as a result.
Prerequisites Before You Begin
To follow along with any method, you’ll need a few things ready. First, ensure you have a GitHub account. If you’re working on an existing repository, you need write access to it—either you own it, you’re a collaborator, or you’ve forked it to your own account.
For the command-line method, you’ll need Git installed on your computer. You can download it from the official Git website. You’ll also need to have your repository cloned locally and your GitHub credentials configured, typically via SSH keys or a personal access token. Having a code editor or terminal ready will complete your setup.
Method One: Creating a Folder on GitHub.com
The web interface is the fastest way to add a new folder when you’re not deep in a local development workflow. It’s perfect for quick additions like documentation, images, or configuration files. Here is the precise sequence.
Navigate to your repository on GitHub.com. You will be on the main code view, looking at the list of files and folders. Look for the “Add file” button in the toolbar above the file list. Click it, and a dropdown menu will appear.
From the dropdown, select “Create new file.” This might seem counterintuitive, but remember the rule: we need to create a file to manifest the folder. Now, in the filename input box, you will define your new folder’s structure.
Typing the Path That Creates Everything
This is the key step. In the text box for the filename, you don’t just type a name. You type the full path of the new file, including the folder you want to create. For example, to create a folder named `assets` and inside it a file named `placeholder.txt`, you would type exactly this:
assets/placeholder.txt
The forward slash `/` is the directory separator. As soon as you type `assets/`, GitHub’s interface will visually recognize you’re specifying a path. You may even see the folder name appear as a pill or badge next to the cursor. The folder `assets` does not exist yet, but by providing this path, you are instructing the system to create it as part of the file creation operation.
Next, you need to add content to this new file. Since the file’s primary purpose might just be to create the folder, you can add minimal content. A common practice is to add a simple comment or a README. For a `.gitkeep` file (a convention to keep an otherwise empty folder in Git), you leave it empty. However, GitHub requires at least one character to create a file. You can add a single space, a period, or a descriptive line like “# This file ensures the directory is tracked by Git.”
Scroll down to the “Commit new file” section. Here, you can add a commit message describing your change. A good message would be “Add assets directory with placeholder file.” You can commit directly to your main branch or create a new branch and start a pull request. Click the green “Commit new file” button. The page will refresh, and you will now see your new `assets` folder in the file tree, with `placeholder.txt` inside it.
Method Two: Using the Command Line and Git
For developers working locally, the command line offers more power and is part of the standard workflow. This method assumes you have already cloned the repository to your machine using `git clone
Open your terminal or command prompt and navigate into your cloned repository’s directory. Use the `cd` command to change directory. Now, you can use standard system commands to create the folder structure. The `mkdir` command makes directories.
To create a folder named `src`, you would run:
mkdir src
This creates an empty `src` directory on your local machine. As we know, Git ignores it. To make Git track it, we need to add a file. You can create a simple file inside it. Using the `touch` command creates an empty file.
touch src/.gitkeep
The `.gitkeep` file is a widely-adopted convention. It’s not a special Git command; it’s just a hidden file whose sole purpose is to ensure Git tracks the parent directory. You could use `README.md` or `index.js` instead, depending on the folder’s future use.
Staging, Committing, and Pushing the Changes
Now, inform Git about the new file. Use the `git add` command, which stages changes for the next commit. You can add the specific file or the entire new directory.
git add src/.gitkeep
Alternatively, to add all new files, you can use `git add .`, but be cautious as this stages every change in your repository. Next, commit the staged changes with a descriptive message.
git commit -m “Add src directory for source code”
Finally, push your local commit to the remote repository on GitHub.
git push origin main
Replace `main` with your branch name if different, like `master` or a feature branch. After the push completes, refresh your repository page on GitHub.com. You will see the new `src` folder and the `.gitkeep` file within it, now part of the project’s history.
Method Three: Using GitHub Desktop
GitHub Desktop provides a graphical interface that bridges the gap between the web and the command line. It’s excellent for those who prefer a visual workflow without memorizing commands. Start by opening GitHub Desktop and ensuring your current repository is selected.
You will need to create the folder and file using your computer’s native file explorer. Navigate to your local repository folder, which you can find by clicking “Repository” in the menu bar and selecting “Show in Finder” or “Show in Explorer.” There, create your new folder (e.g., `docs`) and add a file inside it, like `docs/index.md`.
Return to GitHub Desktop. It will automatically detect the uncommitted changes in your repository. You will see the new `docs` folder and the `index.md` file listed in the “Changes” panel. Check the box next to them to stage the changes.
At the bottom left, fill in the summary field with a commit message, such as “Add docs folder structure.” You can also add a more detailed description. Click the “Commit to main” button to commit the changes locally. Finally, to sync with GitHub, click the “Push origin” button in the toolbar. Your new folder will now be live in the remote repository.
Common Pitfalls and How to Avoid Them
Even with a guide, a few stumbling blocks frequently occur. The most common is trying to add an empty folder and then wondering why it disappeared after a commit. The solution, as we’ve covered, is always to include a file. Use a `.gitkeep`, a `README.md`, or a relevant starter file.
Another issue is case sensitivity. Git treats `Assets` and `assets` as two different folders on case-sensitive systems (like Linux). Be consistent with your naming convention to avoid duplicate, seemingly identical folders. A related problem is special characters or spaces in folder names. While possible, they can cause headaches in scripts and URLs. Stick to lowercase letters, numbers, hyphens, and underscores for the smoothest experience.
Permission errors when pushing from the command line usually mean your authentication isn’t set up correctly. Ensure you’ve configured SSH keys or are using a personal access token with the correct repository permissions. If you’re working on a fork, remember that you push to your fork, not the original upstream repository, unless you are a collaborator.
What About the .gitkeep Convention?
You might wonder about the `.gitkeep` file. It’s purely a community convention. Git has one special file: `.gitignore`. There is no official `.gitkeep`. The file can be named anything. However, using `.gitkeep` has become a clear signal to other developers that this file’s purpose is to preserve the directory structure. It’s immediately recognizable in a file listing. Some projects use an empty `.gitignore` file inside the directory for the same effect, as the pattern is already Git-related.
The alternative is to simply add a meaningful file from the start. If you’re creating a `lib` folder for libraries, add a `lib/README.md` explaining what goes there. This is often the cleaner, more communicative approach.
Organizing Your Repository Like a Pro
Now that you can create folders, how should you structure a repository? Good organization is key to maintainability. A typical web project might include folders like `src/` for source code, `docs/` for documentation, `tests/` or `spec/` for test files, `public/` or `assets/` for images and stylesheets, and `config/` for configuration files.
Many languages and frameworks have common conventions. A Python package often has a folder named after the package containing the `__init__.py` file. A Node.js project might have `src/`, `dist/`, and `node_modules/`. Look at popular repositories in your technology’s ecosystem for patterns to emulate.
Remember, the goal is to make the project intuitive for your future self and other contributors. A logical structure reduces the cognitive load needed to navigate the codebase and find what you’re looking for.
When to Use Submodules or Subtrees
As your project grows, you might consider including code from another separate repository. Git offers submodules and subtrees for this. A submodule is a pointer to a specific commit in another repo. It creates a folder that is essentially a link. This is an advanced feature and adds complexity.
For simply organizing your own code, stick to regular folders. Only venture into submodules if you have a strong need to version and share a component across multiple parent projects while keeping its history separate. The process for adding a submodule does create a folder, but it’s managed with the `git submodule add` command, not the standard folder creation methods discussed here.
Your Repository, Perfectly Organized
Creating a folder in a GitHub repository is a fundamental skill that unlocks proper project organization. The core takeaway is that Git tracks files, so you must create a file within your desired folder path. Whether you choose the quick web method by typing `foldername/file.txt`, the precise command-line approach with `mkdir` and `touch`, or the visual GitHub Desktop workflow, the result is the same: a structured, professional codebase.
Start with a simple structure. Add an `images` folder for your screenshots, a `docs` folder for notes, or a `utils` folder for helper functions. Each new folder makes your project more scalable and collaborative. The initial slight awkwardness of the process fades away, and it becomes a natural part of your development rhythm. Now, go open your most cluttered repository and give it the structure it deserves.
