Git & GitHub Guide

What is Version Control?

Version control is a system that records changes to files over time, allowing you to:

• Track every change made to your code
• Revert to previous versions if something breaks
• Collaborate with others without conflicts
• Maintain a complete history of your project
• Work on multiple features simultaneously using branches

Why Version Control is Essential

Without version control, you might end up with:

my-website.html
my-website-v2.html
my-website-v2-fixed.html
my-website-final.html
my-website-final-REALLY.html
my-website-final-REALLY-THIS-TIME.html

This is chaotic, confusing, and makes collaboration nearly impossible.

With Git, you have:

• One clean codebase
• Complete change history
• Ability to experiment safely
• Professional collaboration workflows

What is Git?

Git is the most popular distributed version control system in the world. Created by Linus Torvalds (creator of Linux) in 2005, Git has become the industry standard for software development.

Key Features

• Distributed: Every developer has a full copy of the repository
• Fast: Most operations are performed locally
• Reliable: Data integrity is guaranteed through checksums
• Flexible: Supports various workflows and branching strategies
• Open Source: Free and community-driven

Git vs GitHub/GitLab

It's important to understand the difference:

• Git = The version control software (runs on your computer)
• GitHub/GitLab = Web platforms that host Git repositories remotely

Analogy: Git is like Microsoft Word, GitHub is like Google Docs.

Remote Repository Services

While Git works locally on your computer, you need a remote repository service to:

• Backup your code in the cloud
• Collaborate with others on the same project
• Share your work publicly or privately
• Deploy websites directly from your repository
• Manage projects with issues, pull requests, and CI/CD

Popular Git Hosting Platforms

1. GitHub (github.com) ⭐ Most Popular

Advantages:

• Largest developer community
• Industry standard for open source
• Excellent collaboration tools (Pull Requests, Issues, Projects)
• GitHub Pages for free website hosting
• GitHub Actions for CI/CD
• Student benefits through GitHub Education

Best for:

• Open source projects
• Portfolio/resume visibility
• Learning from other developers
• International collaboration

Free tier includes:

• Unlimited public/private repositories
• GitHub Pages hosting
• GitHub Actions (limited minutes)
• Collaboration tools

2. GitLab (gitlab.com / gitlab.cn)

Advantages:

• Built-in CI/CD pipelines
• More control over deployment
• Self-hosting option
• GitLab Pages (more flexible than GitHub Pages)
• Good free tier

GitLab.cn (China-specific):

• Hosted in China for better access
• Uses gitlab.com.cn domain for Pages
• Optimized for Chinese users
• Same features as global GitLab

Best for:

• DevOps workflows
• Advanced CI/CD requirements
• Users in China
• Teams needing self-hosting

3. Other Options

• Bitbucket: Good for teams using Jira
• Gitee (gitee.com): Popular in China
• Coding (coding.net): Tencent's platform

Which Should You Use?

For this course and your portfolio:

• GitHub - Best for international visibility and job applications
• GitLab.cn - Best if you're in China and need reliable access

Installing Git

Before you can use Git, you must install it on your computer.

Check if Git is Already Installed

Open your terminal and run:

git --version

If you see a version number (e.g., git version 2.40.0), Git is already installed. If not, follow the installation instructions below.

Installation Instructions

macOS

Option 1: Using Homebrew (Recommended)

brew install git

Option 2: Xcode Command Line Tools

xcode-select --install

Windows

1. Download the installer from git-scm.com
2. Run the installer
3. Use default settings (Git Bash, OpenSSH, etc.)
4. Verify installation in Command Prompt or Git Bash

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install git

Verify Installation

After installation, verify Git is working:

git --version

You should see output like: git version 2.40.0 or similar.

Initial Git Configuration

IMPORTANT: Before you can start using Git, you must configure your identity. This information is attached to every commit you make.

Set Your Name and Email

Every Git commit includes author information. Configure this once after installing Git:

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

Example:

git config --global user.name "Zhang Wei"
git config --global user.email "zhangwei@student.hainanu.edu.cn"

Verify Your Configuration

Check that your settings were saved correctly:

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

Or view all global settings:

git config --global --list

Why This Matters

• Commit Attribution: Every commit you make will be tagged with this information
• GitHub/GitLab Integration: Your commits will be linked to your GitHub/GitLab account if the email matches
• Collaboration: Team members can see who made which changes
• Professional History: Your name appears in the project history

Additional Recommended Settings

Set default branch name to "main":

git config --global init.defaultBranch main

Enable colored output:

git config --global color.ui auto

Set default editor (optional):

# For VS Code
git config --global core.editor "code --wait"

# For nano (simple terminal editor)
git config --global core.editor "nano"

# For vim
git config --global core.editor "vim"

Git Basics and Usage

For comprehensive Git usage, workflows, and best practices, please refer to our detailed lesson:

Lesson 6.1: Git & Version Control

This lesson covers:

• Creating and managing repositories
• Making commits with meaningful messages
• Working with branches
• Collaborating with remote repositories
• Resolving merge conflicts
• Git workflows and best practices
• Common Git commands and patterns

Deploying with GitLab Pages

GitLab Pages is a powerful alternative to GitHub Pages that offers even more flexibility and control over your deployment process.

GitLab Pages vs GitHub Pages

Similarities:

• Both provide free static site hosting
• Both support custom domains
• Both integrate directly with your repository
• Both support HTTPS

Key advantages of GitLab Pages:

• Built-in CI/CD: Uses .gitlab-ci.yml for flexible build processes
• Any static site generator: Not limited to Jekyll - use Hugo, Gatsby, Next.js, VuePress, etc.
• More control: Complete control over the build process
• Larger free quota: In some cases, better resource allocation

How to Set Up GitLab Pages

Here are the most common methods for deploying your website with GitLab Pages:

Method 1: Using GitLab's Built-in Templates (Easiest)

1. Create a new project on GitLab.cn
2. Choose a template or create your static files in a folder structure like:

   your-project/
   ├── public/
   │   ├── index.html
   │   ├── css/
   │   └── js/
   ├── .gitlab-ci.yml
   └── README.md
   

3. Use a simple .gitlab-ci.yml:

   pages:
     stage: deploy
     script:
       - echo "Deploying to GitLab Pages..."
     artifacts:
       paths:
         - public
     only:
       - main  # or master, depending on your default branch
   

Method 2: Popular Static Site Generators

For Hugo:

# .gitlab-ci.yml
image: registry.gitlab.com/pages/hugo/hugo_extended:latest

variables:
  GIT_SUBMODULE_STRATEGY: recursive

pages:
  script:
    - hugo
  artifacts:
    paths:
      - public
  only:
    - main

For Jekyll:

# .gitlab-ci.yml
image: ruby:3.2

pages:
  script:
    - bundle install
    - bundle exec jekyll build -d public
  artifacts:
    paths:
      - public
  only:
    - main

For VuePress/Node.js:

# .gitlab-ci.yml
image: node:18

pages:
  script:
    - npm install
    - npm run build
    - cp -r dist/* public/
  artifacts:
    paths:
      - public
  only:
    - main

Method 3: Complete Step-by-Step Example

Let's create a simple personal website:

1. Create project structure:

   my-website/
   ├── .gitlab-ci.yml
   └── public/
       ├── index.html
       ├── about.html
       └── assets/
           └── style.css
   

2. Create public/index.html:

   <!DOCTYPE html>
   <html>
   <head>
       <title>My GitLab Pages Site</title>
       <link rel="stylesheet" href="assets/style.css">
   </head>
   <body>
       <h1>Welcome to My Site!</h1>
       <p>Hosted on GitLab Pages from GitLab.cn</p>
   </body>
   </html>
   

3. Create the .gitlab-ci.yml file (use the simple one from Method 1)
4. Push to GitLab.cn:

   git add .
   git commit -m "Initial GitLab Pages setup"
   git push origin main
   

Accessing Your Published Site

After pushing, your site will be available at:

https://your-username.gitlab.io/your-project-name

Or if it's a user/group page:

https://your-username.gitlab.io

Custom Domain Setup

1. Go to your project Settings > Pages
2. Add your domain in the "Domain" section
3. Create a CNAME file in your public folder with your domain name
4. Update your DNS settings to point to GitLab Pages

Advanced Features

Environment Variables:

variables:
  HUGO_VERSION: "0.120.4"

pages:
  variables:
    NODE_ENV: "production"
  script:
    - npm install
    - npm run build
  artifacts:
    paths:
      - public

Multiple Stages:

stages:
  - test
  - deploy

test:
  stage: test
  script:
    - npm install
    - npm run test

pages:
  stage: deploy
  script:
    - npm install
    - npm run build
    - cp -r dist/* public/
  artifacts:
    paths:
      - public
  only:
    - main

Monitoring Your Deployment

1. Go to CI/CD > Pipelines to see build status
2. Check Settings > Pages for your site URL and settings
3. View build logs in CI/CD > Jobs if something fails

Tips for China Users

• GitLab Pages on gitlab.cn should have good accessibility within China
• For better performance, consider using a CDN that works well in China
• Keep your site assets optimized (minify CSS/JS, compress images)

GitLab.cn Specific Information

GitLab.cn uses a different domain pattern than the global GitLab service.

GitLab.cn Pages URL Structure

Your GitLab Pages site on GitLab.cn will be available at:

https://your-username.gitlab.com.cn/your-project-name

Or for user/group pages:

https://your-username.gitlab.com.cn

Examples:

· Project page: https://zhangwei.gitlab.com.cn/my-blog · User page: https://zhangwei.gitlab.com.cn

Comparison:

Important Notes for GitLab.cn

1. Different Domain: Notice it's gitlab.com.cn not gitlab.io
2. China-Optimized: The infrastructure is within China, so access should be faster and more reliable from within China
3. Same Setup Process: The configuration using .gitlab-ci.yml is exactly the same as global GitLab
4. Custom Domains: You can still use custom domains with GitLab.cn Pages

How to Find Your Pages URL

1. Go to your project on GitLab.cn
2. Navigate to Settings > Pages
3. You'll see your active page URL displayed there
4. After your first successful pipeline, you'll also see a "Access Pages" button in the project overview

Example .gitlab-ci.yml for GitLab.cn

pages:
  stage: deploy
  script:
    - echo "Deploying to GitLab.cn Pages..."
    # Your build commands here
  artifacts:
    paths:
      - public
  only:
    - main

Summary

Key Takeaways:

• Git is essential version control software that must be installed locally
• GitHub/GitLab are remote repository hosting services for collaboration and deployment
• GitHub is best for portfolio visibility and international collaboration
• GitLab.cn is optimized for users in China with Pages at gitlab.com.cn
• Both platforms offer free static website hosting
• Refer to Lesson 6.1 for detailed Git workflows

Resources

• Official Git Documentation
• GitHub Docs
• GitLab Pages Documentation
• GitLab.cn
• Lesson 6.1: Git & Version Control