Fundamental of Git and GitHub

Git is a free and open-source version control system. It is used for tracking code changes, tracking who made changes, coding collaboration, and much more.

Terminology

What is git?

Git is a free and open source version control system

What is version control?

The management of changes (track of code changes) to documents, computer, program, large web sites, and other collections of information.

Terms

Hint: Don't confuse on Git and GitHub. Git is a version control system, which means it tracks the change of your code over time. You can use Git offline. GitHub is a online website host your repositories, so we can work with other people.

git Commands

Use git and GitHub Generally

Install Git

Check if the manchine already installed Git:

git --version

You should receive a git version number if it has already installed. Otherwise, install git first:

• For Mac: Use homebrew (A package management script) to install git
• For Debian/Ubuntu Linux: apt-get install git
• For windows: Use setup program to install

Set up Key Pairs

GitHub requies uses key paris to check user's authentication. And many features, such as git clone, need key pairs setted up.

Generate a key pairs (Replace the e-mail address to your GitHub E-mail address):

ssh-keygen -t ed25519 -C "your_email@example.com"

By Default, the computer should generate two files:

• id-rsa
• id-rsa.pub

id-rsa is your private key, id-rsa.pub is your public key. DO NOT upload private key to anywhere, it will result in security issues.

You need upload (Settings -> SSH and GPC keys) the id-rsa.pub file contents to GitHub.

cat id-rsa.pub

General Flowchart

Here are some general steps to set up a git repo locally and push to remote.

git init

git init command will set current repo to a git repo.

git init

All git repo should include a hidden .git folder.

.
├── .git
├── .gitignore
├── Chinese
├── English
└── Readme.md

git status

git status command can print informations of current git repo. Like any modifed files, or new files added to the repo.

# user @ machineName in ~/your/dir/path on git:main x [16:19:43]
$ git status
On branch main
Your branch is up to date with 'origin/main'.

Untracked files:
  (use "git add <file>..." to include in what will be committed)
    English/post/2023/04.08.2023.Fundamental of Git and GitHub.md

nothing added to commit but untracked files present (use "git add" to track)

git add

Git can track file changes by using git add command.

To track all changed/Untracked files:

git add .

To track a specific file:

git add [Your File Name]

git commit

git commit will submit all tracked files changes.

git commit -m "Initial Commit" -m "Some more detailed desc."

• First -m as commit message title
• Second -m as commit message description

Be careful: You need at least to write the message title to commit. The description is optional.

Recommended git commit message paradigm

<type>(<scope>): <subject>

Example:

fix(DAO): fixed invalid user table indexes.

type

The type should indicate the category of the commitment, like the following:

• feat : new feature
• fix : fixed bug(s)
• docs : only changed the documentation, such README or CHANGELOG
• test : added/modified the test cases, such unit test or integration test
• style : modified blank lines, format, ordering of import packages, etc. (without changed logic)
• perf : optimized relevant content, such as improving performance, experience, algorithm, etc.
• refactor : refactored (no new features or bug fixes)
• chore : changed the build process, or add dependent libraries, tools, etc.
• revert : reverted to the last version
• merge : code merged

scope (optional)

Scope is used to describe the scope of the commit's influence, and there are different levels of descriptions according to different projects. If there are no special guidelines, it can also describe which functions are affected.

subject

Subject is a short description of the current commit, usually no more than 80 words.

• If it is open source code, you can add the corresponding issue number.

git push / git remote

git push will push the changes to the remote.

Be careful: If you cloned remote repo to local, the remote origin has been automatically set. But if you create a git repo locally, you need to set the origin first before push.

Set repo origin:

git remote add origin [Repository Address]

Check repo origin:

git remote -v

Push the changes to the remote:

git push origin [branch name]

For example (push to main branch):

git push origin main

git clone

Hint: It is highly recommanded use some code editors, such as VS Code, and work with Git together. Of course, you don't have to.

git clone [Repository Address]

For example:

git clone git@github.com:NianwenDan/DSTScripts.git

git log

git log will show history commit.

commit XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX (HEAD -> main, origin/main)
Author: Tom <machine@machine.localdomain>
Date:   Sat Apr 8 15:05:30 2023 -0700

    Add 11.20.2022 to Chinese Post

commit XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Author: Tom <machine@machine.localdomain>
Date:   Sat Apr 8 14:58:03 2023 -0700

    .DS_Store banished!

commit XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Author: Tom <machine@machine.localdomain>
Date:   Sat Apr 8 14:56:52 2023 -0700

git reset

git reset can undo a commit or stages.

Undo a stage:

git reset [File Name]

Undo the last commit:

git reste HEAD~1

Undo to a specific stage:

git reset [Hash Number]

Undo to a specific stage and remove previous commitment:

git reset --hard [Hash Number]

General Workflow

Use Git and GitHub a Little More Advanced

Git Branching

Advantages:

• Develop new features without broke the main branch
• Better team development

Disadvantages:

• Merge Conflicts

git branch

List all branches:

git branch

* main
(END)

Delete feature branch:

git branch -d feature

Delete remote feature branch:

git push origin --delete feature

git checkout

git checkout can switch between different branches, or create a new branche.

Create a new branch:

git checkout -b feature

Switch to main branch:

git checkout main

git diff

git diff shows the changes visually.

git merge

git merge can merge branches.

Pull Request (PR)

Pull Request is using to request the repo owner examine the code, and merge to other branches.

Merge Conflicts

It is easier to fix the conflict on a code editor or the GitHub.