GitHub tutorial on How to correctly use GitHub for your projects by setting up online and local versions of repository
I know that there are already many explanations for getting started with GitHub including the instructions given on the official GitHub site. However I have found in my previous attempts of using GitHub for my projects, that doing things one obvious way instead of the other results in an error which is very hard to resolve for a beginner and as such they will be forced to repeat creating that new repository once again. The most important thing to know is that, the right way to do this is by creating your repository first on the GitHub website and then cloning it into your laptop or PC or wherever it is that, you are working.
I am assuming that you already have a GitHub account and is signed in.(If not, it’s just a few steps of mainly adding your email id and password after clicking on signup). Click on “Repositories” and then click on “New” displayed at top right corner of your screen. You will be greeted with the following page.
On this page, first type in suitable name for your repository where sometimes you might have to keep making changes to the name until the green tick of available appears below your name. I add the name “githubtutorial” for the name of my repository. You can also optionally type something for description knowing that what you type here will appear in the README File of your repository or in other words, it is the text explaining your repo that someone who opens your GitHub repo will see, which can of course be changed later at any time by you. Repos are always better with a README file, so just give that tick for “Add a README file”.
If you are adding a publicly available (meaning anyone can access) GitHub repo by clicking on “Public” button on the page creation page, then it is recommended to add an Open Source Software License. So click on “License:None” below “Chose a license”. In the drop down menu that appears, (optionally read the details of each license briefly by clicking on “learn more about licenses”) chose the license of your choice. If you are not sure, then just chose “GNU General Public License”. So this is how my repo creation page looks now.
So that’s it, Now all I need to do is click on “Create Repository” and now I have a GitHub repository for my project in my GitHub account on the GitHub Website, as can be seen in the image below.
Now we need a local version or in other words a copy of this Repository stored on our PC or Laptop so that we can add files to it or make changes to a file from the system that we usually use for working, and then we can also backup or save those changes or new files to this remote or online version of our Project Repository hosted on the GitHub website/platform on their servers. Firstly you need to get Git (not GitHub) installed on your PC or work system. On Windows operating systems, this is fairly easy by searching for Git Install on Google and then downloading the files from Git website, and finally running the setup file or Installer in the same way that you install apps or games.
After Installing git, you might be forced to add an username and email associated with git on your system. This can be done easily using the following commands one after the other. Replace John Doe within quotes in command below with your randomly chosen username and give your email id without quotes for next command. Just search on Google if you get any error. This is just for name sakes purpose because this is not your username and email associated with the actual GitHub platform that we are using to backup our project, instead this is just the username and email that the git working exclusively on your system associates with the commits you make. Please note that Git and GitHub are totally different where Git is mostly like a command line tool used for tracking and storing the changes you make to each file in your project folder put under git supervision(running $ git init command inside any folder adds git to it or in other words turns it into a GitHub repo) whereas GitHub even though cannot exist without Git is where all the magic and fun happens.
$ git config --global user.name "John Doe"
$ git config --global user.email johndoe@example.comOnce you have correctly installed and configured Git, firstly it is better to create a fresh new folder on your system for your project. Meaning, even if you already have project Folders and files set up on your PC for your ongoing project that you now want to backup to GitHub, just create a new folder with a name identifying your project, but still being slightly different from the name of repository you just made on GitHub site. So I go ahead and create a new Folder on my Windows Laptop with the name “GithubTutorialLocal”. Now you need to get Terminal for Linux based systems and Terminal/Command Prompt for Windows systems opened inside this Folder by using “CD” command if necessary. For Windows 11, you need to just open this Folder like you usually do and then right click followed by (sometimes “more options” and then) “Open in Terminal”.
Now go to your previously created GitHub repo page and then click on “Code” green colored button and select “HTTPS” and finally copy the url given there. (Refer Image below)
Now in the terminal opened on your PC or laptop, type in the command of git clone url_you_copied
git clone https://github.com/SREEHARI1994/githubtutorial.gitHere comes a small extra boring task ,when you run this clone command for the first time after installing git, it is most likely that you will asked in some way to connect your system to your GitHub account. If you think about it, it makes perfect sense to do so because up until now we have done some work over on the GitHub website and then we have done some work on the command line over here on our local system. Now its time to say to both Git and GitHub that it is the same person using them and then connect Git on our local system to our online GitHub account on GitHub website. Earlier this used to be a most simple step of entering our GitHub account’s username and password on the command prompt when asked, but now as per the info on the docs section of official GitHub site, “Password-based authentication for Git has been removed in favor of more secure authentication methods” and so consequently as I have already connected my Git with GitHub in the past using most probably the old password method, I think it’s better for you to read this and do this step on your own. It’s not too complicated or anything, basically you need to first generate a personal access token (by following the instructions in the link shared above in the “this” word) and then when prompted for your password on your terminal/command prompt, enter your personal access token instead of a password. Press Enter and wait for the download to complete and you are done.
Hurray, we got a new Folder with the same name as our GitHub Site’s version of our repository, inside our previously created Folder( this was why I asked you to chose a slightly different name for that folder so as to avoid any confusions with the Folder created by Git clone command).If you now open this newly created folder, you will realize that it has all the files in the same order as your GitHub site Repository page or in other words this newly created folder is just a local version of the repository you created online on GitHub site. Now you might already have your programming files for your ongoing project stored on some other Folder on your system or you might be only about to start work on a new project. In either case, you need to bring your programming files into this newly created Git Folder (one containing .git folder) by either cut or copy paste for it to be included as a part of your official project hosted on GitHub. You are also more than welcome to copy paste whatever nested folder structure or multiple folders structure you have in your project folder stored elsewhere. In other words everything that you put inside this Git Folder can be backed up as such in the same hierarchy to GitHub site. In my case, I am just going to create a new python file inside VS Code called “physics.py”,having a function “calculate_force” that calculates the force applied given mass of an object and save it inside my git folder (along with the README file and .git folder)
def calculate_force(mass):
acceleration = 9.8
force = mass * acceleration
return force
print(calculate_force(float(input("enter mass:\n\n"))))The code above works correctly by printing force as 1960.0000000000002 for a mass of 200. So now that, I have started working on my new Mechanical Engineering Project by writing a simple Python program that calculates Force given mass, I need to make this Python file available on my GitHub repo so that I can share it with others or maybe later publish this as part of a Python package or even to ensure that even if my system malfunctions tomorrow and I lose all my files, I can still get this file on my new system or anywhere else I want to by cloning from GitHub. It can be done easily with just three Git commands of add, commit, push or in other words you first add the file, then you commit which is almost like in quiz shows with the quiz master asking contestant “Are you sure you want to lock this answer?” or commit yourself to a person in a relationship or so on and finally only thing left to do is to push your changes in the form of file additions, deletions or file edits to your GitHub repo. But before that, as a precaution let us first make sure that we will be pushing our changes in project to the correct GitHub repository itself. In GitHub terminology, the online or GitHub hosted version of our project repository is known as “remote” repository while the GitHub folder on your system that you created via cloning can be called “local” version of same repository. Depending on the type of project that you are working on, you can have multiple remote repositories for your local repository and in such a case, each remote repository url has to be assigned a name. Although you are free to chose any name, the main url or the url to the Github repository of your project stored on your own personal GitHub account to which you will be backing up your files is assigned the name “origin”. In our case, because we first started our work on GitHub before cloning to our system, we already have our “origin” repo correctly set up. You can check this by typing in the following command which lists out all your remote repositories with their associated names.
git remote -vAnd you should get as output something like two origin remote repositories, one for fetch and another for push with the url for each one being the same HTTPS url you had initially copied while cloning.
origin https://your_https_url (fetch)
origin https://your_https_url (push)If you did this the other way, by first starting out from your system or for many other situations you might have have to manually add your HTTPS repo url as “origin” and the command to do that is
git remote add origin https://your_urlAll other useful commands concerning Repositories are explained here. Now let’s get to the fun and important part of committing and pushing our changes. Firstly you can do a git status comment to which git responds back with a list of all the changes you made since your last commit including file deletions, insertions or even changes inside a file.
git status
Now you can either chose any from all the changes shown by adding the name of the file you either newly inserted or deleted or made changes to, to the “git add file_name” command. So in my case, I can do “git add physics.py” but instead an easier way especially in cases where you need to push all your changes to your remote origin repo, the command to use is add followed by a dot(full stop) git add . which just adds all file changes to the commit you are about to make
git add .Now all you need to do is commit your changes and push to GitHub and it is always better to complete these three steps of add, commit, push in one go. While committing you are required to write a short commit message describing your latest change and this is for helping you as well as any other individual collaborating on your project understand the change that you are making. This message along with the date you made this change will be shown next to your file on your remote GitHub repo. So in my case, I am just going to use “first version of force calculator”
git commit -m "first version of force calculator"Before pushing your changes, I just wanted to mention that GitHub works with branches with each branch having different versions of your same project code and up until now, as we have not created any new branches for our code, we are still using the default branch which is currently called “main” by GitHub, but in the past it used to be called “master”, so when you clone your fork(explained later) of popular open source repos on GitHub like MongoDb’s mongo and then later you push to it, you will have to push to “master” instead of “main”. That all being said, this is the command to finally push your changes to GitHub and be done with it
git push origin mainThe actual syntax for this command is given below and you can read more here
git push REMOTE-NAME BRANCH-NAMEAnd that’s it!!!! Now when I login into my account on the GitHub site and go to my project repository page, I can see and rejoice that my newly created “physics.py” file along with details of my latest commit are now a part of my GitHub repo.
As an additional info which I might explain later in more detail if I were to write another advanced GitHub tutorial article covering everything else important in GitHub, in order for you to become a contributor to an open source project on GitHub by contributing to another person’s repository, you need to first create a “fork” or your own copy of that repository (to be included as part of your own repositories hosted on your GitHub account) by clicking on the fork button on that repository page and then once you get your own copy of that opensource repository on your GitHub repos section, you need to clone to your local system, make your changes, commit and push those changes to this fork or copy, using the same steps as mentioned in this article and then finally all you need to do is click on “create a pull request” under Pull requests section and once the maintainer of that open source repo approves your pull request and merges the changes you made to your fork to his original repository, you too will be listed as a contributor to that open source library repository. You can try this yourself and find out that, you only have permission to push your changes to repositories in your personal GitHub account linked or coupled with the Git on your local system and you cannot ever make changes to anybody else’s repository directly without first creating its fork.
