Git Guide

Posted on Edited on In Word count in article: 1k Reading time ≈ 4 mins.

This is a simple guide for basic settings of Git and workflows with Github.

Setting up the environment

Installation

SSH conection to your account (Github)

  1. Generating a new local SSH key

    1
    2
    ssh-keygen -t ed25519 -C <your email address> 
    ssh-keygen -t rsa -b 4096 -C <your email address> # use this instead if your system doesn't support ed25519

  2. Adding your SSH key to your account. The public key is usually stored in the folder .ssh/. Cpoy the content of id_rsa.pub to GitHub –>> Settings –>> SSH and GPG keys –>> New SSH key. Verify the connection by the following command. 

    1
    2
    $ ssh -T git@github.com
    Hi username! You've successfully authenticated...

  3. Setting global user information

    1
    2
    3
    4
    5
    6
    7
    8
    # The name and email address here don't have to be the same with github username, it's just for identification
    $ git config --global user.name <your name>  
    $ git config --global user.email <your email address>

    $ git config --global user.name
    username
    $ git config --global user.email
    email@domain.com

Setting agent

1
2
3
4
5
# proxy only for github
git config --global http.https://github.com.proxy socks5://127.0.0.1:<proxy port number>

# cancel the proxy
git config --global --unset http.https://github.com.proxy

Workflow

Starting a repository

Before doing this, make sure you have set user.name and user.email in git setting (see 1.2 step2).

  • remote empty repository & local empty folder

    1. Create a remote empty repository by pressing new button.

    2. Start with git init by creating a local folder (you’d better build a folder with the same name as the remote repository). 

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      mkdir <repository name> && cd <repository name>
      echo "# SomeRepo" >> README.md
      git init 
      git add README.md  

      # only after the first commit of a repository can you change or rename branch name
      git commit -m "first commit"
      git branch -M main  # -M: force move to branch main

      git remote add origin <repository url>  # you can choose either HTTPS or SSH here
      git push -u origin main

      Or you can start with git clone but not git init.

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      git clone <repository url>
      cd <repository name>

      echo "# SomeRepo" >> README.md
      git add README.md

      # only after the first commit of a repository can you change or rename branch name
      git commit -m "first commit"
      git branch -M main  # -M: force move to branch main

      git push -u origin main

  • remote non-empty repoitory & local empty folder

    1. Create a remote repository with README.md or .ignore. Or simply you can start with an existing repository.

    2. Start with git init by creating a local folder(you’d better build a folder with the same name as the remote repository). 

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      mkdir <repository name> && cd <repository name>
      git init
      git remote add origin <repository url>  # you can choose either HTTPS/SSH here 

      # only after pulling the remote branch and commit to local can you change or rename branch name
      git pull origin main
      git branch -M main

      echo "test" >> test.txt
      git add text.txt
      git commit -m "local commit"
      git push -u origin main

      Or you can start with git clone but not git init.

      1
      2
      3
      4
      5
      6
      7
      git clone <repository url>
      cd <repository name>

      echo "test" >> test.txt
      git add text.txt
      git commit -m "local commit"
      git push -u origin main

  • remote non-empty repository & local non-empty folder

    1. Create a remote repository with README.md or .ignore. Or simply you can start with an existing repository.

    2. Start with git init by creating a local folder(you’d better build a folder with the same name as the remote repository). 

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      mkdir <repository name> && cd <repository name>
      git init
      git remote add origin <repository url>  # you can choose either HTTPS/SSH here 

      # only after pulling the remote branch and commit to local can you change or rename branch name
      git pull origin main
      git branch -M main

      echo "test" >> test.txt
      git add text.txt
      git commit -m "local commit"
      git push -u origin main

Creating a new branch

  1. Check your current branch with command git branch.

  2. Copy current branch to a new branch and check out the new branch. 

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    # method 1
    git chechuot -b <new-branch> # -b means create new branch

    # method 2
    git switch -c <new-branch>
    git switch --create <new-branch>

    # method 3
    git branch <new-branch>
    git switch <new-branch>

Basic snapshotting

  1. When some files are changed, use git add command.

    1
    2
    git add <changed files>
    git add .  # add all changed files to local index

  2. Check status of tracked files.

    1
    git status

  3. Record all changes in the index to the repository.

    1
    git commit -m <commit message>

  4. Push local repository to remote

    1
    git push origin <branch name>

Making a pull request

  1. Make New pull request on Github.

  2. The host of that repository accept the new pull request then Squash and merge.

  3. After the new branch is merged to main branch, first delete the new branch on Github. Then delete the new branch locally.

    1
    2
    3
    4
    5
    git checkout main
    git push -d <remote_name> <branch name>  # delete remote branch
    git branch -d <branch name>  # delete local branch
    git fetch --all --prune  # fetch branches
    git pull origin main  # pull the new commit to local main

Handling with conflicts

  1. Make sure local main branch is up to date.

    1
    2
    git checkout main  # switch branch to main
    git pull origin main

  2. Reapply new commits on main branch to new branch

    1
    2
    3
    git checkout <branch name>
    git rebase main
    git push -f origin <branch name>  # force push local repo to remote

Useful commands

1
2
3
4
5
6
7
8
9
10
11
git diff  # show changes between commits, commit and working tree
# run :q to exit

git add <file name>  # add file content to the index
git branch  # show current branch
git checkout  --orphan  <new branch name>  # create a new branch without history commit

git pull origin main  # pull remote repository to local
git push origin main  # push local repository to remote

git fetch --all --prune  # fetch remote branches and delete branches that do not exist

Reference