top of page

GitHub Setup Guide

  • karmariv7
  • Aug 3, 2025
  • 6 min read

Updated: 7 days ago



What You'll Learn

This guide will walk you through setting up your first project with GitHub.  By the end, you'll understand how to track changes to your code and store it safely in the cloud.


What is Git? Git is a version control system that tracks changes to your files over time. Think of it as a save system for your code that lets you go back to any previous version and see exactly what changed and when.


What is GitHub? GitHub is a website that hosts Git repositories in the cloud. It allows you to back up your code, share it with others, and collaborate on projects. While Git runs on your computer, GitHub provides a central place where your code lives online.


What are the benefits of versioning your code in GitHub


  • Backup: Your code is safely stored online

  • History: See every change you've made and why

  • Collaboration: Work with others without overwriting each other's work

  • Portfolio: Showcase your projects to potential employers


Table of Contents


Prerequisites

Before you begin, you'll need to set up your environment:

  • Install Git

    • Go to git-scm.com/downloads and download git for your OS

    • Run the installation and follow the default options

    • Verify installation by opening your terminal/command prompt and typing 

git --version

  • You should see the git version displayed

  • Go to github.com and create an account if you don't have one


Setup and Deployment Steps

1. Create a repository in GitHub 

  • Go to github.com 

  • In the upper-right corner select "+" icon and choose "New Repository"

  • In the repository name add a name for your project, and add a description (this is optional)


  • Choose whether your project will be public or private (this value can be changed later)


  • For now do not add a README file (we can create this later)


  • And leave "Add .gitignore" and "Add license" options set to None (we will get back to this later)



2. Initialize your local repository

In your local environment, navigate to your project folder and initialize Git

cd /path/to/your/project-name
git init 

This command creates a hidden .git folder in your project directory. This folder contains all the version control information. You only run this command once per project.


Configure the user name and user email in your local environment, this step is important because it helps Git to track who made each change

git config --global user.name  "Your Name"
git config --global user.email "your.email@example.com" 

3. Configure and connect your local repository to GitHub

Now that the repository in GitHub is ready,  and the local repository has been initialized, it's time to connect them. 

To do so, go to you GitHub repository and copy the URL:



Next, go back to the command line and type:

Note: The "remote add" command creates a connection to the remote repository. "origin" is the name that you are giving to this connection by convention we use "origin" but you could use any name.


If you want to check if your remote has been correctly configured

git remote -v

This command will show the name "origin" (or the name that you have chosen) follow by the github repository URL


4. Create Essential files (Optional)

This step is optional, but as a best practice it is recommended to include them in your project.


.gitignore

.gitignore tells Git which directories/files to ignore. This prevents sensitive data (passwords, API key or personal data) from being committed. It also helps to keep a clean repository by filtering out any system generated files or temporary files.


Let's say that your project has the following structure:


YOUR_PROJECT

|--- .gitignore

|--- main.py

|--- examples/

|     |--- sample_1.csv

|     |--- sample_2.csv

|--- venv/

|     |-- include/

|     |--  lib/

|     |--  scripts/


If you want to ignore the file test.py and folders examples and venv then .gitignore content should look like this:

# files
test.py
# folders
venv/
examples/

To create the .gitignore file type

nano .gitignore

Note: you can use any text editor


Provides information about your project. It is the first thing that people see when they visit your repository.

You can find more details and guidelines about how to document and format your content in this guide from GitHub.


To create the README.md file type


requirements.txt

This file contains a snapshot of all Python packages and versions currently installed in your environment. It helps anyone that clones the project be able to recreate the exact Python environment.

Run the following command to create the file:

pip freeze > requirements.txt

Now you are ready to start working on your project!


Stage and Commit files

What is staging? Git uses a two-step process: staging and committing. Staging lets you choose which changes to include in your next commit. This is useful when you've modified multiple files but want to commit them separately with different messages.


You can use git status to check which files have been modified

git status

This will show the following output:



This output shows:

  • Which modified files have not been staged yet

  • And staged files ready to commit


1. Staging Files

There are two options to add files to the stage area


Option 1: Stage all changes at once

git add .

Note: The period means "everything in the current directory."


If you run git status it will show all the files ready to be committed:



Option 2: stage specific files

git add file1.txt
git add file2.txt

In this case if you run git status, you will see what files are ready to be committed and the ones that have been modified but will be left out.



Use this option when:

  • You've worked on multiple features and want separate commits

  • You want to review each file before staging

  • Some files aren't ready to be committed yet


Note: After staging run "git status" again to confirm which files are ready to commit


2. Commit changes

A commit is like a snapshot of your work at some point in time. Each commit:

  • Records what changed

  • Stores who made the changes and when

  • Includes a message explaining why the change was made


git commit -m "Initial commit" 

The -m flag lets you add a message inline. It is a good practice to keep it short, and clearly indicate the purpose of the change. Good messages help you and others to understand what changed and why.


Commits create your project's history. Good messages help you (and others) understand what changes and why.


3. Push your changes

The push command takes your changes and uploads them to a remote repository.

The first time that you push your changes run the following command to align your branch name to the one in GitHub

git branch -M main

The "-M" option renames your default branch to the name that you add in this case "main".


Note: GitHub uses "main" as the default branch name, but Git use "master."


Next, push your changes. In this case origin is the name that you assigned to your remote repository (3. Configure and connect your local repository to GitHub) and main is the local branch where changes are located

git push -u origin main

What happens:

  • Git packages your commits

  • Sends them to GitHub over the internet

  • GitHub updates your repository

  • Your code is now visible in github.com


The first time you push your changes, GitHub will ask you to authenticate. Follow the prompts to create a Personal Access token if you haven't already


This command will produce the following output:


After the first push, you can simply use:

git push

Note: Git remembers where to push thanks to the -u flag you used initially.


Next Steps

Congratulations! You've successfully set up version control system for your project and pushed your first commit to GitHub. You now have:

  • A backed-up copy of your code

  • A history of all your changes


Recommended workflow going forward

  1. Make changes to your code

  2. git status -check what changed

  3. git add. - stage your changes

  4. git commit -m "Descriptive message" - Commit with a clear message

  5. git push -upload to GitHub


In our next article, we'll cover branching strategies and collaborative workflows. For now, practice this basic workflow until it becomes second nature.



bottom of page