Beginner’s guide to GitHub: Uploading files and folders to GitHub

Welcome back to GitHub for Beginners, a series designed to help you navigate GitHub with ease.

If you’ve been following along, we’ve covered some basics of Git and GitHub, including the top Git commands every developer should know and how to create repositories. Now that you have a repository, you can use it to track file versions or collaborate with others. However, first you need to upload your files to the repository.

Let’s get started!

How do I upload files?

There are multiple ways you can upload content to GitHub, and we’ll go through a few of them. The first option we’ll cover is uploading using GitHub.com.

To upload a file to GitHub, you’re going to need a repository to upload the files to. We covered this in our previous how to create repositories blog, but as a quick refresher, you’ll need to click the button or menu option for creating a new repository. On the next screen, select an owner for the repository, give it a name, provide a description, choose whether it is public or private, and initialize it with a README.md file. Then, click the “Create repository” button.

Once you’re in your repository, click on the plus button next to the green button that says “Code.” Select “Upload files” from the menu. On the next screen, click the link that says, “choose your files.” This opens up a file browser and you should select the files you want to upload.

Depending on the size of the files, it might take a moment for them to upload, but you can see the files being added to your commit on the main screen. It’s important to realize these files aren’t uploaded to the repository yet. You still have a couple of short steps to go.

Next, add a commit message in the box under the list of files to be added. You can leave the default commit message, but it’s often helpful to provide a brief description of the changes you’re making. This gives anyone with access to your repository insight into what changes were made. Next, click the green button that says, “Commit changes.”

Now your files will be uploaded to your repository! This is a great way to add small files to GitHub. However, there’s another way that can be more convenient for uploading large files, folders, and entire projects.

How do I upload files using the terminal?

Before we use the terminal, we should create a new empty repository. In GitHub, click the plus button at the top and select “New repository.” This time, only enter a name and a description. We want the directory to be completely blank. We decided to call our repository python-game.

Click the green “Create repository” button.

After your repository is created, you’ll see a window with some instructions and a list of Git commands you can use from a terminal. These are the steps we’re going to follow to push our files to GitHub.

On your local machine, open a terminal and navigate to the project folder you want to upload. In our case, that’s the python-game directory, so we run cd python-game from the projects directory.

The first step is to run git init in the folder. git init initializes the folder and organizes it so that it can be used as a repository.

Next, we want to add a README.md file with a brief description, so let’s run touch README.md to create the file. You can now open the file (in the terminal or your file manager) and add a brief description that describes the repository.

Now, we need to tell Git which files to add to the repository. We do this by running the git add . command. This adds all of the files in our current directory to staging. The next step is to run git commit -m "initial commit" to create a commit with a description of “initial commit.” A commit is like a snapshot of the current state of the files in your local repository.

To make sure everything worked, run git status and verify that all the files are ready to be pushed. You should see a message indicating that your working tree is clean.

Now, run git branch -M main to set the main branch. The next step is to connect your local repository to the repository on GitHub. You do this by running git remote add origin and replacing the with the URL provided on the GitHub instructions page when you created the repository. This essentially tells Git “this is where I want you to put these files.”

The final step is to run the git push -u origin main command. This sends all of the files to GitHub. Go back to your browser and refresh the page. You should see the files uploaded to GitHub and residing in your repository! Congratulations!

<img src="https://github.blog/wp-content/uploads/2024/06/git-add-cli-3.gif" alt="An animated gif showing "git status" and "git remote add origin

Now, if you already initialized Git in your project on your machine, and you just need to upload your files to a remote repository, you wouldn’t need to run git init at the start. You’d follow the rest of these steps, but skip that initial one.

What’s next?

Now that you have learned how to add files and folders to your repositories, it’s time to start using them to collaborate with others or add version tracking to your files!

If you have any questions, pop them in the GitHub Community thread and we’ll be sure to respond.

Here are some more resources to help you on your GitHub journey:

• GitHub Foundations Certificate
• Adding a file to a repository
• Deleting files from a repository
• Large files on GitHub

Written by

Kedasha Kerr

@ladykerr

Kedasha is a Developer Advocate at GitHub where she enjoys sharing the lessons she's learned with the wider developer community. She finds joy in helping others learn about the tech industry and loves sharing her experience as a software developer. Find her online @itsthatladydev.