Author: contr4l_
Git and GitHub are currently the most popular code management solutions (similar solutions include the tearful SVN of the era, gitlab and gitee based on git, etc.). In this tutorial, readers will be guided step by step to complete tasks such as installing Git, pulling GitHub repositories, modifying and submitting code, etc., laying the foundation for embracing open source.
Installing Git#
Git is a command-line program that provides a series of functions for downloading, submitting, and managing branches. The download address is: Git Download. For Windows, it is usually recommended to choose Standalone Installer: 64-bit Setup (if it is a very old 32-bit system, you can choose 32-bit Setup).
Now press Win+R, enter powershell, and run it. In the window, enter git -v, and the following should appear:
PS C:\Users\ctrl> git -v
git version 2.40.0.windows.1
- The version information may vary depending on the installed version of Git.
- If an error message is displayed, consider whether there was a problem during the installation of Git or whether the path where git.exe is located has been correctly added to the system's environment variables.
Registering on GitHub and Adding SSH Key#
First, you need to register a GitHub account. Please resolve any network connection issues with GitHub/Google on your own (in general, direct connection to GitHub is smooth, but there are many problems in some educational network systems, which are related to regional network service providers).
The current registration page is really cool. Google is a great company, haha.
Now you can log in to your GitHub account.
Before we perform git clone, there is an important thing we need to do, which is to add our local SSH key to our GitHub account. Follow these steps:
# 1. In powershell, enter ssh-keygen.exe and press Enter all the way
# I added the -f option here to avoid overwriting the generated public key
PS C:\Users\ctrl> ssh-keygen.exe -f github
Generating public/private rsa key pair.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in github
Your public key has been saved in github.pub
The key fingerprint is:
SHA256:JJ+NVRVXLj2aWTGQj+5Jx6edEnpQG146uqvMmbR9uhI ctrl@CtrlPC
The key's randomart image is:
+---[RSA 3072]----+
| .o=++|
| . . +o|
| . . . +oo|
| + = +=+.|
| S . ++* |
| E . O o.|
| .. * =oo|
| +.=o *...|
| Bo*B . |
+----[SHA256]-----+
# 2. Continue by entering cat ~/.ssh/id_rsa.pub
PS C:\Users\ctrl> cat ~/.ssh/id_rsa.pub
ssh-rsa ****** ctrl@CtrlPC
# 3. Copy the long string starting with ssh-rsa from the screen
# 4. On the GitHub page, click on your profile picture in the upper right corner, then go to Settings-SSH and GPG keys-New SSH key
# 5. Paste the long string you just copied into the Key text box, and click Add SSH key. The Title can be left blank.
Pulling a GitHub Repository#
Now you need to access our wiki repository.
First, you need to fork this repository into your own repository. This is the basis for making modifications and submitting them.
Make sure to uncheck the option "clone main branch only"! We are developing based on the gh-pages branch.
Now you can see that contr4l.github.io is under your name, as shown in the following figure.
Next, we will pull the code. First, find the SSH code pull address, as shown in the figure below, and then enter git clone {the .git address you just copied} in powershell.
PS C:\Users\ctrl> git clone [email protected]:fakeContr4l/contr4l.github.io.git
Cloning into 'contr4l.github.io'...
remote: Enumerating objects: 242, done.
remote: Counting objects: 100% (242/242), done.
remote: Compressing objects: 100% (145/145), done.
remote: Total 242 (delta 69), reused 202 (delta 35), pack-reused 0Receiving objects: 67% (163/242), 1.63 MiB | 39.00 Ki
Receiving objects: 100% (242/242), 1.69 MiB | 45.00 KiB/s, done.
Resolving deltas: 100% (69/69), done.
Now you will have a new folder named contr4l.github.io in your current directory, which is our working directory.
Switching Branches and Editing/Submitting Code#
First, we need to switch from the default main branch to our working branch gh-pages.
cd contr4l.github.io
git checkout gh-pages
# The prompt should be as follows:
# Switched to branch 'gh-pages'
# Your branch is up to date with 'origin/gh-pages'.
Then we need to establish a tracking relationship between our own repo and the original repo, and keep the local code up to date.
# Add an upstream git
git remote add upstream [email protected]:contr4l/contr4l.github.io.git
# Fetch the latest content from upstream
git fetch upstream
# remote: Enumerating objects: 101, done.
# remote: Counting objects: 100% (101/101), done.
# remote: Compressing objects: 100% (26/26), done.
# remote: Total 63 (delta 8), reused 63 (delta 8), pack-reused 0
# Unpacking objects: 100% (63/63), 857.91 KiB | 53.00 KiB/s, done.
# From github.com:contr4l/contr4l.github.io
# * [new branch] gh-pages -> upstream/gh-pages
# * [new branch] main -> upstream/main
# Synchronize the latest changes from upstream to local
git pull upstream gh-pages
# From github.com:contr4l/contr4l.github.io
# * branch gh-pages -> FETCH_HEAD
# Updating e820fac..b08386a
# Fast-forward
# ...
Note that before making any modifications, you need to execute
git pull upstream gh-pagesto avoid conflicts between your local modifications and the remote.
Now you can make any modifications to this repo in your local editor and use docsify's real-time preview to ensure that the modifications meet your expectations.
Finally, you need to push the modifications to your own repo. Follow these steps:
# First, make sure you are in the root directory of contr4l.github.io
pwd
# Path
# ----
# C:\Users\ctrl\contr4l.github.io
# Add all modifications to the staging area
git add .
# Commit the changes with a commit message
git commit -m "{Enter your modification description in double quotation marks, e.g., translate armor page}"
# Push the changes to the gh-pages branch of your own repo
git push origin gh-pages
# PS C:\Users\ctrl\contr4l.github.io> git push
# Enumerating objects: 5, done.
# Counting objects: 100% (5/5), done.
# Delta compression using up to 12 threads
# Compressing objects: 100% (3/3), done.
# Writing objects: 100% (3/3), 381 bytes | 381.00 KiB/s, done.
# Total 3 (delta 2), reused 0 (delta 0), pack-reused 0
# remote: Resolving deltas: 100% (2/2), completed with 2 local objects.
# To github.com:fakeContr4l/contr4l.github.io.git
# e820fac..7ce3e7d gh-pages -> gh-pages
Finally, submit a pull request to the upstream branch, requesting to merge your modifications into the release branch. Pay attention to the following points:
- Both the original branch and the target branch should be gh-pages (if you have made changes on other branches locally, choose accordingly).
- You must create the pull request from your own repository, not contr4l's repository.
Now you can see your new pull request in the pull request list of contr4l's repository, as shown in the following figure:
At this point, you need to check if the modification content below matches your modifications.
Also, make sure there are
no conflicts. If there are conflicts, it means that your modifications overlap with existing modifications. You need to resolve the conflicts locally before submitting.
To resolve conflicts in VSCode, simply choose
use your commitoruse remote commit. It's very easy.