About & How to Git - A Simple guide to using the Git Version Control System

This description is intended to familiarise and hasten the introductory process for any individual trying to acquaint themselves with Git. Many VCS's exist and technical-oriented organisations equip themselves with commercial grade VCS's for adequate support. Companies' genre include Software and IT firms or, firms requiring constant upgrade of team contributions to be tracked in an efficient way.

 

What is Git?

Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency.It is easy to learn and has a tiny footprint with lightning fast performance. 

A modern VCS, that was initiated in 2015 by the founder of Linux-Mr.Linus Torvalds and is actively being managed by a community and many other proprietary-originated firms that supply support and active storage management for commercial organisations.
Git extends as a minor component for Agile Software Implementation methodology and is also intended for Agile Business environment.

 

What is a version control system?

Version control systems are a category of software tools that help a software team manage changes to source code over time. Version control software keeps track of every modification to the code in a special kind of database. If a mistake is made, developers can turn back the clock and compare earlier versions of the code to help fix the mistake while minimizing disruption to all team members.

Basics

The use of term "main git" is only intended to specify abstraction. In reality, there is no main git as this VCS is a distributed type VCS. Distributed means all contributors must host a local copy on their system that has been intialised for VCS through git init or git clone.The main git referred to here is to the webpage accessible git repository usually present at the URL or a server hosting a central copy.

1. Repository : The main database folder that holds the files and folders within it that must be included in the VCS to track changes
2. Fork:Fork is a copy of the original repository. It allows the user to simply experiment with existing repo without reflecting changes on the original repo. Primarily used when exploring other developer's completed projects.
3. Merge:It is used by the repo master to integrate the final changes on the main repo. It has many capabilities such as topic addressed merging, etc. Simply, a final integration for various commits from different developers on same/different branches can be achieved.
4. Commit: Any change in the repo component of the locally existing files and folders require the developer/master to commit and then push onto the main git on respective on various branches. Typically, after doing the same, one is capable of
5. Push:This command will push any amends in the local repo onto the main git for comparison with other contributors' repos.
6. Pull:This command will import changes from the main repo that is a final copy always under update and monitoring from th master branch.
7. Branches: To track changes and new features to an existing project, branches come in use. For instance, a developer can keep developing a beta feature on a seperate branch. After the master is assured of integration for this beta feature onto the main project, the master will execute a merge for all amends into the main repo so that the resultant will have a new stable project with the new feature.
8. .gitignore:This file contains the intentionally untracked files for the VCS so that any changes will not be tracked for the mentioned untracked files.
9. .readme.md: The usual readme file for reference. The extension md-markdown will display on the main repo page in the html format.

 

Setting up your system for Git

Although many GUI's exist, I prefer the use of CLI(Command-line interface) based Gitbash. In my opinion, it suffices the basic needs of a typical contributer only interested in push-pull-commit cycle for the git process. 

-Installing Git : For windows or Linux, goto https://git-scm.com/downloads

-Adding the SSH Public Key for secure commits by https://help.github.com/en/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent and then https://help.github.com/en/articles/adding-a-new-ssh-key-to-your-github-account

-Any operations for Git will fail without the above step

 

Some simple commands to fast-forward your way

Command	Description	Example
git init	Intialise a git repository with header objects i.e. .git(translucent folder) appearing at the mentioned path or the path at which you intend to clone an existing repository	git init
git config --global user.name "firstname.lastname"	The git header where the git init was executed will be configured with the user name replaced by firstname,lastname. Any updates commited will reflect the given name on the main git page	git config --global user.name "John.Doe"
git config --global user.email "myemail@myemail.xyz"	The email address will be the contact email address for the developer/master making commits to VCS through this local repository	git config --global user.email "john.doe@domain.suffix
git clone the web address where the main git exists	This command will clone the folder the user wishes to download from the main git page	git clone https://...../my_git_repository_online &nbsp OR git clone ssh1@ssh1domain.something/my_git_repository_online
git status	Verifies for any ammends on the repo for the given branch	git status
git checkout -b new_branch	A new_branch will be setup. Comes handy when developing different features for a team project	git checkout -b developer
git merge master new_branch	The integration or merge of various features after review executed by the owner or master for the repo to update the central database with the final copy that will reflect the changes into the local copy throuh a git pull on the master branch	git checkout -b developer

Github and Gitlab

Both github and gitlab are web-based repositories for Git-based VCS.

Github has been since long a storage platform for open-source projects. Lately, Gitlab has announced its capability for a complete DevOps status that includes a highly detailed documentation for resource utilisation. Furthermore, many experts have suggested better response in terms of CI/CD integration. On the contrary, github is a large repo for most Open Source Codes that may come in handy for most developers.

For the typical user, it's not important to know about gitlab or github in detail as the decision for hosting on whatever platform is the organisation's decision. Often cases may also arise such that file based or local server based repos may be setup on the existing gitlab structure for privacy reasons.
 

An Example on Github

Say in academia, your colleagues and you have been tasked with developing a simple VHDL Project that implements a calculator performing Arithmetic or Logical operations. The tasks have been divided among three teammates and each of them are required to describe an individual component of the final hardware.

Step 1:Tasks for the team leader

• The team leader say member 'A' will setup a new project named 'VHDL_Calc' on the github portal over his account. By navigating through settings for the given project, the other members can be added as collaborators. It is necessary to specify the other contributors as developer status
• 'A' will clone this repository on his local PC. For doing so, simply navigate to X:/my_project locally.
• Then right-click and initiate gitbash here.
• Execute the git config commands and clone the existing repo
• git config --global user.name "PersonA"
• git config --global user.email "PersonA@personA.somedomain"
• git clone git@github.com:PersonA's_git_username/VHDL_Calc
• cd VHDL_Calc

• Person A can now see the .git translucent folder in this directory when accessed through Windows Explorer

Step 2:Team Leader will setup the folder structure and readme.md

• execute the following python script for automatic folder structure setup as per template(not necessary) 

-----------make a new text file python.py and save with extension .py in the project folder------------------------------------------
 ---------------------------------------------------
#!/usr/bin/env python

#########
# Execute this script inside your repository to create the empty folders
#########
import os
import sys

FIRST_LEVEL = ['component_codes','project_folder']

def safe_make_folder(i):
    '''Makes a folder if not present'''
    try:
        if not os.path.exists(i):
            os.mkdir(i)
    except IOError:
        print "Wrong path provided"

def make_firstlevel_folders(level_1):
    for i in level_1:
        safe_make_folder(i)
    #open(PATH+sys.argv[1] + os.sep +".gitignore","w+")

def main():
    make_firstlevel_folders(FIRST_LEVEL)

if __name__ == "__main__":
    main()

• Person A's gitbash: python python.py -requires python2.7 installed on the system
• Person A will edit the readme via notepad. 
• The folder component_codes are the codes where the main VHDL codes will be uploaded by each contributor
• project_folder is the folder within which the Xilinx ISE or Xilinx Vivado folder project will be setup

• Person A's gitbash
• touch readme.md
• git add readme.md
• git commit -m "Initial Commit"
• git push -u origin master OR git push

Step 3: Cloning of repo by other contributors

• Person B and C will navigate to X:/my_project and initialise git bash here through right click.
• On Bash:
• git config --global user.name "PersonB"
• git config --global user.email "personB@personB.somedomain"
• git clone git@github.com:Person_A's_git_username/VHDL_Calc

The repository will be cloned for both the collaborators

Step 4: Person B and C

• Describe the VHDL codes for AND and OR gates respectively
• The files should be saved in the component_codes folder as AND_g.vhdl and OR_g.vhdl
• After saving the same, both 'B' & 'C' open git bash:
• git checkout -b developer_branch
• git add .
• git commit -m "My code is ready"
• git push

Step 5: Person A - verifies the changes appearing on the developer_branch code and merges the same on master branch

• On person A's gitbash:
• git status
• git merge master developer_branch
• git pull
• git branch -d developer_branch
• git status

 Step 6: Main Project-Execution

• 'A' will then setup a new Xilinx Project and mention the sources listed in component_codes folder
• The main person will now setup the top level hardware as a new VHDL file that will instantiate the AND and OR components.
• The project will be synthesized and implemented to generate simulations through testbench.

 Step 7:Final Upload for finished project

• Person A's gitbash:
• git add .
• git commit -m "Finished project"
• git push

Step 8:All Collaborators update their local repos for final project

• on Person B & C's gitbash:
  • git status
  • git pull 
   

Finally, each collaborator has completed the most trivial contribution for git workflow towards delivering their team project. 

 

References: -

• https://git-scm.com/
• https://www.atlassian.com/git/tutorials/what-is-version-control