I wrote a tutorial on Git. In this post, I’d like to introduce the platform that is indispensable when it comes to Git: GitHub.

As mentioned in the article about Git, GitHub is a platform for hosting remote Git repositories. Think of it simply, as a little cloud drive that you can use to sync (upload, download) your code and communicate with other developers.

Creating a Github Account

See:

• Getting started with your GitHub account

Checking your Local Git Config

Make sure that you have told Git your name and email. That is say, you should have run:

git config --global user.name YOUR_NAME
git config --global user.email YOUR_EMAIL

Also see:

• Basic Configuration - Simple Git Tutorial
• Setting your username in Git - GitHub Docs
• Setting your commit email address - GitHub Docs

Connecting to GitHub with SSH

You are recommended to connecting to GitHub with SSH (instead of HTTP/HTTPS).

First, generate a new SSH key using new ED25519 algorithm:

ssh-keygen -t ed25519 -C YOUR_EMAIL

Then, Keep on repeating pressing Enter until your prompt appear again.

Finally, add your public key to GitHub:

1. Go to SSH and GPG keys - GitHub.
2. Click the green New SSH key button at the top right of the page.
3. Fill out the form, where key is the content of ~/.ssh/id_ed25519.pub (This file is generated by the ssh-keygen command above. You may run cat ~/.ssh/id_ed25519.pub on Linux or Mac or run notepad ~/.ssh/id_ed25519.pub on Windows to check its content).
4. Submit the form by clicking the green Add SSH key button.

Also see:

• Connecting to GitHub with SSH - GitHub Docs

Using SSH over the HTTPS port (Optional but Recommended)

Due to the special network environment in China, you may often need to use proxy service to get a better browsing experience. Generally, when you enable the System Proxy option, only the traffic on port 80/443 (corresponding to HTTP/HTTPS) will go through the proxy server, while the traffic on SSH’s default port 22 will not. With the following settings, you can force SSH traffic to go to port 443.

To test if SSH over the HTTPS port is possible, run:

ssh -T -p 443 [email protected]

Type yes if you see some info like:

Are you sure you want to continue connecting (yes/no/[fingerprint])?

If you receive response like below, it means it’s OK:

Hi USERNAME! You've successfully authenticated, but GitHub does not
provide shell access.

You can now override your SSH settings to force any connection to GitHub.com to run through that server and port. Edit ~/.ssh/config and add this section:

Host github.com
    Hostname ssh.github.com
    Port 443
    User git

Now your usual command like:

git clone [email protected]/YOUR-USERNAME/YOUR-REPOSITORY.git

is equivalent to:

git clone ssh://[email protected]:443/YOUR-USERNAME/YOUR-REPOSITORY.git

Also see:

• Using SSH over the HTTPS port - GitHub Docs

Basic Concept & Usages

Cloning

Repository (Repo) is a concept in Git that refers to a place where your code is stored. Repositories can be categorized as local or remote. You can use the git clone command to clone a repository from GitHub, i.e. to clone a local repository based on a remote repository. The command format is as follows:

git clone URL [LOCAL_DIRECTORY_NAME]

where center brackets mean that LOCAL_DIRECTORY_NAME is optional.

On the front page of any GitHub repository, you’ll find a green Code button; clicking on it will bring up a tab with HTTPS and SSH tabs (you must be logged in to see the SSH tabs). For public repositories that you don’t have editing or modification rights to, you can use their HTTPS links to clone them; if you wish to edit a repository, you must use the corresponding SSH link.

git remote set-url origin SSH_URL

git remote -v

origin    [email protected]:YOUR_NAME/YOUR_REPOSITORY.git (fetch)
origin    [email protected]:YOUR_NAME/YOUR_REPOSITORY.git (push)

If you want to specify a branch when cloning, you can use -b option:

git clone -b BRANCH URL

If you don’t want to include all commits, you can use the --depth option. This is helpful when cloning a large repo (you don’t need so many commits before actually).

git clone URL --depth=1

Issues & Pull Requests

Issues and Pull Requests (PR) are two of the most important collaboration features on GitHub. With an Issue, you can point out problems with a codebase, suggest improvements, request new features, etc. With a Pull Request, you can ask the administrator of a codebase to merge your submitted code for the purpose of contributing to that codebase.

GitHub Workflow

Nothing helps you grasp how to use GitHub faster than learning by example. Below are two GitHub workflows to help you better understand the basic concepts and usage of GitHub.

Team Work

The following example workflow assumes you want to collaborate with your team members on a project and that you are the team leader responsible for creating and managing the repository:

1. First, go to the GitHub homepage, click the plus button on the right side of the top toolbar, and select New repository from the dropdown menu.
2. Fill in the basic information for the repository, including the repository name, and specify the repository type (the default is Public, but in a group project context, you may prefer it to be Private). Once completed, click the Create repository button at the bottom right of the page.

3. After creation, you will be automatically redirected to the repository page:

4. Follow the prompts on the page to execute the corresponding commands locally (remember to switch to SSH first):

• If you haven’t created a local repository yet, create a new directory (e.g., named teamwork-example), then cd into it and selectively execute the following commands:

echo "# teamwork-example" >> README.md # Create a README.md file
git init # Initialize a Git repository
git add README.md # Add the newly created README.md to the staging area
git commit -m "first commit" # Commit with the message "first commit"
git branch -M main # Rename the current branch to main
git remote add origin [email protected]:YOUR-NAME/teamwork-example.git # Add a remote repository named origin
git push -u origin main # Push to the main branch of the remote repository named origin

• If you already have a local repository, just cd into it and execute the following commands:

git remote add origin [email protected]:YOUR-NAME/teamwork-example.git # Add a remote repository named origin
git branch -M main # Rename the current branch to main
git push -u origin main # Push to the main branch of the remote repository named origin

5. Return to the GitHub repository page; you should now see your code here.

6. So far, only you have edit permissions for this repository. If you want to invite your group members, click on Settings in the top toolbar, select Collaborators in the left Access section, and click the Add people button on the right:

The invited collaborators will receive an email notification. By following the instructions in the email, they will gain edit permissions for the repository. Then, collaborators can clone the repository using the SSH link, make changes locally following the regular Git workflow, and finally use git push to push changes to the remote repository. Once a collaborator pushes, others can use git pull to fetch the latest changes.

Contributing Code to an Open Source Project

The following example workflow assumes you want to contribute code to an open-source project:

1. First, go to the homepage of the open-source project and click the Fork button in the upper right corner.

2. On the new Fork page that you are automatically redirected to, customize the relevant information as needed or keep the default, then click the Create fork button.

3. Now you should be redirected to a repository with the same name (if you did not change the default settings in the previous step). Under the repository name, it will indicate the source of this fork. For example, in the image below, the public repository is withastro/astro, and my GitHub username is BlockLune, so the forked repository is named BlockLune/astro.

4. Clone this repository to your local machine using the SSH link.

5. In your terminal, navigate to the project’s root directory and run the following command to create a new branch and switch to it. The BRANCH_NAME should be descriptive and conform to the project’s conventions (for example, if you want to add a new greeting feature, your branch name might be feature/greeting):

git checkout -b BRANCH_NAME

6. Execute your Git workflow. For example, edit files and use git add and git commit appropriately to save changes, ensuring that your commit messages are descriptive and conform to project conventions.

7. When you believe your changes are complete, return to GitHub and navigate to the public repository address of the project. Click on Pull requests at the top to enter the pull request tab, then click the green New pull request button on the right.

8. On the new pull request page, choose the base and compare branches. base indicates the branch you want to push to; compare indicates the branch where your new feature resides (e.g., feature/greeting), which you want the other party to pull from. After making your selections, click the green Create pull request button.

9. The page will automatically redirect to a new pull request page. Here, you can communicate with the repository maintainers or others, and continue to submit new commits to this branch regarding any issues or possible improvements you discover. Observe the URL of this page, which looks like https://github.com/REPO_OWNER/REPO/pull/ID. The ID is incrementally generated; Issues and PRs increment together, so the first Issue or PR in the repository has the ID #1, the second is #2, and so on.

10. If the work in your branch is to fix a specific issue (for example, #2), you can also add keywords like Close #2 in the description text to link your PR to that Issue, which will automatically close the associated Issue when the PR is merged. For more information on linking PRs to Issues, refer to Linking a pull request to an issue.

11. The next steps will be the repository owner’s responsibility: they will review your code and, if everything is correct, merge your branch (completing the pull operation). Once merged, the commits from the contribution branch will be integrated into the base branch in some form, at which point it is safe to delete the contribution branch (the compare branch mentioned above).

Learn more:

• Hello World
• GitHub flow

Related Git Commands

# add a new remote server
git remote add NAME URL

# remove a specific remote server
git remote remove NAME

# set (update) the URL of a remote server
git remote set-url NAME URL

# show remote servers
git remote -v

# rename a remote server
git remote rename OLD_NAME NEW_NAME

# some info about a specific remote server
git remote show NAME

# push
git push -u NAME BRANCH # or `git push --set-upstream NAME BRANCH`

# fetch
git fetch  # from the default remote upstream repo
git fetch NAME  # from a specific remote upstream repo

# fetch & merge
git pull

Repository Statistics

You can see the Languages section on the right side of the GitHub repository page that shows information about the languages used by this repository. This information is generated by github-linguist/linguist.

Sometimes you may want to have some control over the information here (e.g. you may want to categorize Jupyter Notebook as Python), so it’s useful to know where they come from. One possible way to do this control is to use .gitattributes, for example:

*.ipynb linguist-language=Python

Learn more:

• linguist/docs/overrides.md at main · github-linguist/linguist

GitHub Profile

You can create a profile page by creating a repository with the same name as your GitHub username and adding a README.md file to it. This page will appear on your GitHub personal page. For example, my repository is BlockLune/BlockLune, which is displayed on my GitHub personal page.

Many people will choose to add some statistics here. there are actually a number of specialized projects on GitHub for generating these statistics, for example:

• anuraghazra/github-readme-stats
• ryo-ma/github-profile-trophy
• DenverCoder1/github-readme-streak-stats

Learn more:

• Customizing your profile

Resources

• Simple Git Tutorial | BlockLune’s Blog
• Simple Git Tutorial: Branching and Merging | BlockLune’s Blog
• GitHub Docs