A guide to Git
— git gud
“ This is not a complete guide for git, but just to give people a small understanding on how to use git”
Brief Background : What is Git ?
To put it simply, Git is a version control tool. Version control simply, is a tool to help you control changes and keeping track of it. You can work your code step by step, with git saving your each step, you won’t have to worry on making mistakes as you can go back to the previous backup copy. To give you an example…
Imagine you’re making a sandwich🥪. Let’s also imagine you have a fancy refrigerator called Git that can make special copies of each step of your sandwich making places on an infinite number of shelves.
Step 1 : You start with two slices of bread and add it in Git. Git now contains two slices of bread on one of it’s shelves.
Step 2 : You add a slice of cheese to your sandwich and also add it to Git. Git now contains a slice of cheese on the shelf just above the last shelf.
Step 3 : You add a slice of ham lettuce and add it to Git. Ham and lettuce sits on a shelf.
Step 4 : You add ketchup. ketchup sits on a shelf.
But wait, putting ketchup was a mistake. So you go into Git and get the sandwich as you built it up to step 3. So now you’re back to the sandwich with no ketchup and now you can put the correct condiment, mustard. Rolling back this way is much better than scraping the ketchup off because you might miss some of it.
Git also has the ability to keep the sandwich as is but also let you experiment on another copy (Forking). It’ll store this fork on a new set of shelves beside your ‘main’ shelf.
by mtx (from reddit thread “ Can you explain me GIT like i’m 5 years old.”)
From my experience, using git can be hard… whether its merge conflicts, or reverting etc (I’ll explain this more later on), making changes can be confusing for inexperienced git users. You may end up spending lots of time scratching your heads, or losing your tracked files completely!
Sounds scary right? But don’t worry! Git will really help you if used properly and here I’ll try my best to guide you!
Lets Get Started! : Installation and Setup
For windows
Step 1 : You need to download git first here
Step 2 : After instaling, Start the installer, you’ll see the Git Setup wizard, click “ next ” until the “ finish “ prompt.
Step 3 : Open your command prompt and run the command below(without the “$” sign)
$ git --version
git version 2.17.1 //this is the output in your terminal!Step 4: Configure your git username and email (this will be used for commits)
$ git config --global user.name "<insert-your-username>"
$ git config --global user.email "<insert-your-email>"For linux
Step 1 : You can get Git by “ apt “
$ sudo apt-get update // use this first to update your package list
$ sudo apt-get install gitStep 2 : Open your terminal and run the command below
$ git --version
git version 2.17.1 //this is the output in your terminal!Step 3: Configure your git username and email(this will be used for commits)
$ git config --global user.name "<insert-your-username>"
$ git config --global user.email "<insert-your-email>"And git has finally installed in your system yay!
Basics of Git: Repositories
1. Repositories
Simply, a Repository in Git is similar to a project folder that Git could track all the changes inside the folder. To create one you need to have an accout in a git repository hosting service such as Gitlab or Github. (Ill be explaining by using Gitlab)
So, If you want to have a repository
Step 1 : Click on the new project on the top nav-bar
Step 2 : Add the name of your project. Visibility level means your current repository visibility setting for other users. Private means No one can see your repository unless you allow them to, Public means everyone can see your repository. (I won’t initialize README first in my case as I’ll explain more later on how to “ git init ”)
Step 3 : You have successfully created your repository!
“ I know you all must be thinking… its still empty and how do we connect our repository into the folder”
Git init
- git init way(this is used if you have an existing folder and you want to put it onto a repository)
git init is a command that creates a “skeleton” .git folder this enables us to make a git folder in our local to become a git repository 😀
Step 1: Use the git init command in your desired folder (in my somefolder directory it already contain a helloworld.txt file)
Step 2 : We need to use the
$ git remote add origin <your-git-repository-url>The command is basically telling our folder to be tracked into a repository. This could also act as a backup remotely.
Step 3 (I’ll explain more about the code later): Now we want to “ push “ our folder into the online repository.
Step 4: Now check your repository online.
Git clone
git clone is a command in git which is used to get an online repository into your local directory(the repository itself may be empty or has existing files). The command would be…
$ git clone <the-repository-url>Lets try it out!
Basics of Git: Pushing
So you have made changes to your file in git, but how do you push it into your online repository? Yup, you guessed it by Adding it, committing it, the pushing your work.
- git status : To see unstaged/staged files.
- git add
git add is a command in git which adds any changes in a/any file in your working directory into staging area. Several git add commands:
// adding a specific file
git add <file-name> // adds all changed files in the working directory
git add . // adds all files in the working directory
git add -A
Me personally most of the time uses git add . because I can directly add all of my changed file.
3. git commit
git commit is used to record and name your changes. Your commit message will be used on the timeline of git changes of your repository (so name it as detail, concise and as short as possible).
// Adds a commit message
git commit -m "your message here"// changes your most recent commit message
git commit --amend "your new message"// Combine commits, so our commit timeline wont be messy
git rebase -i
4. git push
git push is a command to push our staged files, as when we commit, the changed files has not been pushed into our online repository yet. We need the git push command to push into our repository
git push origin <your-branch>Your main branch is master. But in large projects, with lots of people, everyone pushing to master would cause problems. Which is why we need “branching”, which will be explained in the next section.
Precautions!
(This precautions is for people doing in projects)
When we a member of your team has pushed/merged into the masters branch or your parent branch. Make sure to git pull as soon as possible. using the command:
git pull <remote> <branch-name>//If you all working in the same repository
git pull origin <branch-name>
This enables us to get the most up to date changes and avoid huge conflicts later on (I’ll explain more about conflicts and how to resolve it later on!).
Mandatory git: Managing Branches
In my eyes, I see git has a tree like structure. When we create a new repository, we have a main branch called “master”. I consider “master” as the trunk of the tree itself. Like trees, Git also has branches that we can create. Simply branches is an extension of master (our main branch) which we can modify, make changes, without affecting our master branch. However, if we want to apply our changes into our master’s branch we can “merge” our branch into master (which will be explained below).
Step 1 : To create a new branch use command
git checkout -b <your-branch-name>
Step 2 : Lets add another file in the sub-branch.
Step 3 : Now we push into our branch
Step 4 : Now lets check in our git
Step 5 : To “ merge “ our sub-branch into master we need to make a merge-request.(Its okay you can do this in any branch regardless)
Although its not necessary, description is used to describe what changes or features made in your current branch, In very large projects describable descriptions help greatly for your superiors to review your code. Assignee, is to assign a person to review your branch changes. Do note that the members need at least a maintainer role to accept the merge.
Step 6 : Merge it (click the green “ merge “ button)
Before it is merged, members of the repository can review and add comments regarding your code. “Delete source branch” means once your branch is merged with master, the branch is deleted . This helps as when your project gets larger, branches will also grow. We need to maintain the branches (imagine having 100 useless branches).
Step 7: Voila! our new file has been merged to master!
Now that I have explained on how to create branches, What if we want to traverse other branches? easy.
git checkout <target-branch>Git Merge Conflicts
Now, when a code is changed in different line or files, git can resolve the changes by itself, however, when git could not automatically resolve the differences between 2 commits, you would need to manually choose, which changes you would like to keep. This event is known as a merge conflict.
Take an example below:
We have a file named example_function.js , in branch master. That contains a function named checkValue.
function checkValue (value) {
if(value) {
return "The value is True!"
}else {
return "The value is False!"
}
}Now, say we have other branches namely branch branch_john_doe owned by John Doe has different implementations of checkValue, but at the same time, you would like to merge other unrelated changes from John’s branch.
branch_john_doe:
function checkValue (value) {
return value ? "This value is True" : "This value is False";
}So when we use the command git pull origin branch_john_doe in our master branch, git firstly fetch the any updated commits, then merge it.
As you can see here, we are experiencing a merge CONFLICT. Because there are 2 same changes within the same file. Git cannot choose which changes should be chosen hence we need to manually update the change and resolve the conflict.
We can also see on which commit that causes the conflict using the command, to tell John Doe to update the following changes from the master branch. We can see this using the git log command.
If the commit is not clear enough we can use, the git diff <your_branch_name> <the_merged_branch_name>`function. To check which differences occurs when pulling/merging.
Now, other than telling john to update his changes, another way is to fix it by yourself. The current conflicting file looks as below
We can say “HEAD” as the current branch that we are working on. The lines between beginning <<<<<< and ======== is what we have locally. The lines between ======== and >>>>>>>>>>> marks the pulled commit. The string characters on the end indicates the SHA ID commit when doing the pull changes. These all are known as conflict markers.
So to fix the conflict, we would just have to ‘choose’ which changes to be applied unto our local.
IDE’s such as JetBrains products or Visual Studio Code provide an easy picking to choose between which version you would like to apply to, such as below.
However, you can also do this manually, by erasing the HEAD and other conflict markers, and choosing either one or (possibly both) changes from the 2 commits.
Here I decided to use John’s function as it is more elegant. Then we would just need to git add . and add the commit message and conflict is resolved!
Tips
In team projects, conflicts would happen regularly. Several tips to not break your project are:
- It is better to use fetch first not pulling. Why? because having a local copy of another branch could give additional options (checkout to their branch and check first etc.)
- Merge Constantly! You should constantly update any work from the committed upstream. That way, when there are conflicts, you would only need small amount of resolving.
- Communicate. Make sure to communicate with your group/ team members when resolving changes, to avoid unintended changes.
- Use IDE! Manually resolving conflicts is tedious process and could cause human errors when removing the conflict markers, hence more time to fix it.
In our group, we assign Ilman for back-end related and me for front-end related changes to check during resolving conflicts. This ensures no unintended changes in our project.
Advanced git: Git stash
git stash is a command in git which is used to save any changes you have made since your last commit. From my personal experience, I use git stash mainly if you want to move branches, but you don’t want to commit yet.
// Stashes your current work
git stash//Removes the stash and apply it
git stash pop//Apply your stash but doesn't remove from stash
git stash apply//See the list of existing stash
git stash list//Clears the stash
git stash clear//Apply or pop(and apply) of a specified stash
git stash pop/apply stash@{<number>}
(I’ll add an implementation about stashes in the future so stay tuned!)
Advanced git: Revert and Reset
Mistakes do happen. But its okay, with git it allows us to backtrack, revert changes!
//Switch to the most recent commit
git reset HEAD
git reset HEAD --filename //for a specific file//Clear any uncommited changes to the most recent commit
git reset --hard//Fully change to the commit (this will affect the commit history and repository)
git reset --hard <commit-hash>//Revert back to a commit (this will make a new commit)
git revert <commit-hash>
I find git reset --hard is quite dangerous to used, because it alters the commit history and the repository itself… so be careful when using it. The safest bet is the git revert command, as it adds a new commit when reverting.
I rarely used revert or reset when doing projects as I am very careful of my commits, therefore I have very little experience regarding reverting or reset.
But you can read this great article about revert and reset I found by NeshaZoric.
(I’ll add an implementation about revert in the future so stay tuned!)
Conclusion
There are lots of git functions that are not covered in here, and please see also the git documentations to have a greater overview on how git works (as my explanation may be wrong). But thank you for reading! hope it helps on your journey to understanding and using git! Cheers!
