Git is a distributed version control tool that runs on Linux, Unix, Mac and Windows. With the help of Git, you don’t have to manually record and save copies every time when the files are changed, or worry about file exchange and protection when working on big projects with others. This post introduces common usage of Git.

Installation Link to heading

Git installation on Linux is simple, just type “git” in terminal and follow the hint.

Git installation for Linux 

$ git
The program 'git' is currently not installed. You can install it by typing:
sudo apt-get install git
$ sudo apt-get install git

Set your user name and email address. “global” means that all Git repositories on your machine will use this configuration, yet you can can use different names and email addresses for different repositories.

Git Configuration 

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

Create a Repository Link to heading

First let’s create a local git repository, so that all the files in the repository are managed by git, which means all the changes to the files can be tracked by git. For example, I create a repository in folder “/home/teng/chatbot”.

git init 

$ git init
Initialized empty Git repository in /home/teng/chatbot/.git/

Now we can work on the files in the directory. To actually add the file to the repository, it takes 2 steps: 1. add the file to “stage” using “git add”, and 2. commit the file to the “branch” we are in (default “master”) using “git commit”. The concepts of stage and branch will be explained later on.

workflow 

$ git add .
$ git commit -m "fix io bugs"

For convenience, here I use a dot “.” after “git add” to add all the files in the directory, you can put the file name that you want to add, e.g. “bitcoin.txt”, or the folder to add all the files in that folder to stage area. When working with a existed codebase and need to remove files for code refactoring, you may often use ‘git add -u’, where ‘-u’ refers to ‘–update’, stages modifications and deletions, but not new (untracked) files, since ‘git add’ does not automatically stage deleted (removed) files. Of course to add untrack files, ‘git add’ works fine.
The parameter “m” after “git commit” means message, you are always recommended to add some description for the changes in the commit. If you want a more refined message that consists of multiple lines, ‘git commit -F file’ command is used to create a commit using the commit message from a file instead of typing it manually in an editor or using -m.

commit with a long message

The commit message in msg.txt: 


Feature: Add knowledge graph support
- knowledge graph on file level for rag mode, function level for default mode. 
- Visualization of graph generated in folder ./visualizations
Then commit with file: 

$git commit -F msg.txt

Or do it all in shell using git commit -F - with a here-document (« EOF … EOF) to pass a commit message directly via standard input (stdin), without needing a file:


$git commit -F - << EOF 
Feature: Add knowledge graph support
- knowledge graph on file level for rag mode, function level for default mode. 
- Visualization of graph generated in folder ./visualizations
EOF

Remote Repository Link to heading

The first git command I used is ‘git clone’, which is to clone a repository from github and save it to the local computer. We can also upload the local reporitory to remote github server to share the project with others. To communicate with the server, it is necessary to have a SSH key. Check if there are two files named “id_rsa” and “id_rsa.pub” in folder “.ssh”, which locates in the user directory, for example, “/home/.ssh”. If you cannot find the files, create the SSH key first:

$ ssh-keygen -t rsa -C "youremail@xxx.com"

Then we can go to github -> Settings -> SSH and GPG Keys and click “Add SSH Key”, paste the content of “id_rsa.pub”. If we want a repository same as the local one online, and synchronize the two repositories, first we should log in github webpage and create a new repo with the same name as the local repository, then push the local content to the remote repo following the instructions github given.

$ git remote add origin git@github.com:tengma137/chatbot.git
$ git push -u origin master

If we fork a repository from others and work on that repo, use “git clone” to download the repo, “git add” & “git commit” to edit files locally and “git push” to update the changes to the remote repo. Here’s how it looks like:

$ git clone git@github.com:user_name/repo_name.git
$ git add .
$ git commit -m "fix io bugs"
$ git push origin master

Branch Management Link to heading

If you want to develop a new feature without affecting the main branch, or work on multiple tasks in parallel, for safy and a clean dev structure, start on a new branch is your best choice.

branch workflow 

// Start from main branch, make sure your local main is up to date with the remote. 
$ git checkout main
$ git pull origin main 
// Create a feature branch called feature/dark-mode
$ git checkout -b feature/dark-mode
// Work and commit locally
$ git add .
$ git commit -m "Add initial dark mode toggle"
// Push the branch to the remote
$ git push -u origin feature/dark-mode
$ git commit -m "fix io bugs"

You could also use ‘git switch main’ to change current branch to work on, note that if you have uncommitted changes (like edited files or new code) and try to switch to another branch, Git will either block the switch or cause conflicts—especially if the changes would clash with the branch you’re switching to. To avoid losing or conflicting with your work, Git provides a handy tool: git stash.


// You're working on main and have uncommitted changes
git status
// You want to switch to 'feature/login' branch and do your work
git stash            # Save changes
git checkout feature/login 
git checkout main    # Go back
git stash pop        # Restore your original changes

‘git stash list’ lists all the changes you saved.