Blog

Embarking on your journey into the world of version control with Git can be both exciting and rewarding. Git's ability to track changes, facilitate collaboration, and streamline development makes it an essential tool for every developer. In this article, we'll guide you through the foundational steps of Git, from initializing a repository to making your first commit.

If this is your first contact with git version control, you can find more about how Git is organized in this article: Mastering Collaboration: A Guide to Effective Git Workflow

Setup and Context

In order to take the steps presented below, you need to have a code editor installed (I prefer Visual Studio Code - VSCode) and have Git installed. If you are using Windows, there is a simple installer available on the official Git website. Follow the instructions presented here: Getting Started Installing Git

With VSCode and Git installed, you can create a folder somewhere on your PC, name it however you like, and open it in VSCode (File/Open Folder). One of the features I like in VSCode is that you can run any terminal in the editor. After opening the project folder (I will use a Projects folder created directly on C:\ and have a project1 folder inside), go to Terminal/New terminal in the top menu, or simply press Ctrl/CMD + Shift + ` keys to do that.

I prefer using the bash terminal for git commands, but you can also use PowerShell or other terminals as well.

Click on the terminal dropdown to select the Git Bash terminal.

In the bash terminal, you should already be in your project folder. However, if you are not, you can use the "cd" command to navigate to the project folder:

cd /c/Projects/project1

Step 1: Initializing a Repository

Before you can start version controlling your project, you need to create a Git repository. This is where Git will track changes to your files over time. To initialize a repository, open your terminal and navigate to your project's directory. Then, use the following command:

git init      # Initialize a new Git repository in your current directory

This command initializes a new Git repository in your current directory, creating a hidden .git folder to store all the repository's data. You're now ready to start tracking changes.

Step 2: Adding Files to the Staging Area

Before adding the files to staging area we first need to have some files to work with. You can download this simple index.html file that we use in our example or create any text file you want in the initialized project folder.

Git has a staging area, also known as the index, where you can prepare changes before committing them. This allows you to selectively commit specific changes rather than all modifications. To add files to the staging area, use the git add command:

git add <file-name>

For example, to add the file named "index.html" to the staging area:

git add index.html

You can also use wildcards to add multiple files:

git add *.html      # Adds all HTML files
git add src/*.js    # Adds all JavaScript files in the src directory

When working on projects with a large number of files and where the changes you've made between commits involve multiple files, it's better to use git add . command, as you don't need to target all the files you've changed:

git add .      # Adds all files in the current directory

Altough git add . may be considered to be too agressive as it includes all the files in the current directory, used in combination with the .gitignore file, which we will use later, is very effient in commiting multiple changes.

Step 3: Making Your First Commit

A commit is a snapshot of your changes at a specific point in time. Once you've added your changes to the staging area, it's time to commit them to your local repository. Use the git commit command:

git commit -m "Your commit message here"

The -m flag is for providing a commit message that describes the changes you made in this commit. A good commit message is concise and descriptive, helping you and your collaborators understand the purpose of the changes.

I prefer using "initial commit" when creating the first commit on a new project, so that I know that it was the very first commit created.

Step 4: Renaming the Master/Main Branch (optional)

The main or master branch is the branch where the initial commit is added. From this branch you can create further branches and merge them back.

The name is not important but sometimes you may prefer one vs the other. If you prefer "main" vs "master" for the main branch (or whatever other name), now is a good time to change it.

To change the name of the branch, first run the git branch command to see what are the existing branches and what is the branch you are working on. Only "main" or "master shoudl exist right now."

git branch
*master
git branch -M main

The git branch command is the command used for managing branches in Git. The -M flag stands for "move" and "force" and it's used to rename the branch and overwrite the new name if it already exists, while main is the new name of the branch. Since there is only one branch, you don't need to specify the name of the branch you want to rename. However you can use the following command then dealing with multiple branches:

git branch -M master main

This will rename the "master: branch into "main" branch.

You can learn more about git branches in this dedicated article: Demystifying Git Branches: A Comprehensive Guide

Step 5: Connecting to a Remote Repository

To collaborate with others and share your code, you'll need a remote repository. This is typically hosted on platforms like GitHub, GitLab, or Bitbucket.

If you don't have an account to a collaboration platform that uses Git, you should create one now, in order to continue with this step.

I will continue with GitHub as an example for creating a git repository but you can use whatever platform you use.

After creating the GitHub account you need to create a new Git Repository. On the repository creation page you should add a project name, I named mine project1, just like the repository I have set locally to avoid any discrepancies between the local and remote versions.

When creating a new repository you can stick with the github defaults for now, just add the repo name, leave the repository public, don't add a readme.MD file for now and leave .gitingore to none, we will create one later. Click "Create repository" and you are done.

That's it! You've created a new repository.

On the result page you find valuable infor about the steps you need to take next:

To connect your local repository to a remote one, use the git remote add command:

git remote add origin <remote-url>

Here, "origin" is a common name for the remote, you can use whatever word you want, and <remote-url> is the URL of your remote repository. After adding the remote, you can push your changes to it using git push and pull changes from it using git pull.

Now you have created the staging for the first commit localy and you have connected that local repository to a remote repository. The next thing to do is tu push that local repository to the remote repository.

You can check the existing remote connections of this local repository with the git remote -v which will show you the fetch and push repositories.

git remote -v
// This should output the remote repos connected to this local repo, in my case: 
// origin  https://github.com/vivianvanatu/project1.git (fetch)
// origin  https://github.com/vivianvanatu/project1.git (push) 

Step 6: Push the local repository to the remote repository

You can use the git push command to push the local repository to the remote one. By now, your local repository is connected to the remote repository (git remote add origin <remote-url>), so if you push the local repository git will know where to send it.

git push

When running git push for the first time in a local repository, you will get a fatal error in the terminal as well as the solution for that error.

This happens because there's no estabilished tracking between local and remote repositories. The alternative is to either mention the origin and the branch in the push command or to set up tracking between local and remote repositories. I prefer the second solution, to set up tracking between local and remote repos. This means that after this initial push, you can simply use git push and git pull without specifying the remote and branch names. Git will automatically know which remote and branch to push and pull from.

To set up tracking, you can simply use one of the following commands at the initial push:

git push --set-upstream origin main			// git push --set-upstream <origin> <branch-name>

// or the shorthand version:

git push -u origin main					// git push --set-upstream <origin> <branch-name>

I prefer writting only git push and when I get the error result I simply copy and paste the suggested command git push --set-upstream origin main as it is already filled with origin and branch name.

Congratulations! You've taken your first steps in Git, mastering essential commands like git init, git add, git remote add, git commit, and git push. These foundational skills are the building blocks of efficient version control and collaboration. As you continue your journey, you'll discover more advanced Git concepts and techniques that will empower you to manage projects effectively and work seamlessly in collaborative environments. Happy coding!