Version Control, Git, GitHub, and Quarto

Google Docs for the class. We can use this as a class notebook.

Logistics

• Is 10:00 - 12:00 on Thursday a good time for office hours?
• Make an appointment with Kwok-leong by the end of the forth week.
• Enrolled students will have priority in scheduling office hours with Kwok-leong.

KL’s Objectives

• Persuade you to use VSCode, Git, GitHub, and Quarto to write your articles, presentations, and dissertations.
• Understand why we use version control, Git, and GitHub instead of Google Docs.

Major and Trending Tools in AI-Assisted Coding (contined from last week)

There are many emerging tools in the AI-Assisted Coding space. We will cover a few of them here.

GitHub Copilot

• GitHub Copilot is an AI-powered code completion and coding assistant for GitHub.
• It has two extensions for IDEs: “GitHub Copilot” and “GitHub Copilot Chat”. You can search them in the Extensions section of VSCode.
• The GitHub Copilot extension is for code completion and inline suggestions.
• The GitHub Copilot Chat extension is for chat-based code generation.

Cursors

• Cursors is an AI-powered IDE based on VSCode.
• Cursors is a subcrption-based service, so you need to pay for it ($20/month).

Cline

• Cline is a free extension for VSCode.
• To access LLM usage, you will need API keys.
• Cline documentation provides a lot of good ideas and templates: Cline Documentation.
• We will explore Cline in our future lectures.

Replit & Project IDX

• Replit and Project IDX is are online IDEs that runs on cloud servers. You can access them from any machine with modern browsers and internet connection.
• Both Replit and Project IDX have a free tier and a paid tier.

Package Managers

Homebrew and Winget are package managers designed to simplify the installation, update, and management of software on macOS and Windows systems, respectively. They streamline the process of handling software packages, making it more efficient for users to maintain their systems.

Homebrew (macOS)

Homebrew is a package manager for macOS (and Linux) that allows users to install and manage free and open-source software via the command line. It’s particularly favored by developers for its simplicity and the vast array of packages available.

Installation on macOS:

1. Open Terminal: You can find Terminal in the Utilities folder within your Applications, or by searching for it using Spotlight (press Command + Space and type “Terminal”).
2. Install Xcode Command Line Tools: Before installing Homebrew, ensure that you have the necessary command line tools. Execute the following command:

xcode-select --install

3. Install Homebrew: Once you have Xcode Command Line Tools installed, run the following command to install Homebrew:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

This script will download and install Homebrew on your system. Follow the on-screen instructions during the installation process.

4. Verify Installation: After installation, confirm that Homebrew is correctly installed by running:

brew --version

This command should display the version number of Homebrew.

Basic Homebrew Commands

1. Install a Package: To install a package, use the brew install command followed by the package name.

brew install <package_name>

2. Update Homebrew: To update Homebrew itself, use the brew update command.

brew update

3. List Installed Packages: To list all installed packages, use the brew list command.

brew list

4. Uninstall a Package: To uninstall a package, use the brew uninstall command followed by the package name.

brew uninstall <package_name>

5. Upgrade a Package: To upgrade a package, use the brew upgrade command followed by the package name.

brew upgrade <package_name> 

Winget (Windows)

Winget, or the Windows Package Manager, is a command-line tool for Windows 10 and Windows 11 that enables users to discover, install, upgrade, remove, and configure applications. It serves as a convenient method to manage software installations on Windows systems.

Installation on Windows:

Winget comes pre-installed on Windows 11 and modern versions of Windows 10 as part of the App Installer. To verify if Winget is installed, open the Command Prompt or PowerShell and type:

winget  --version  

If Winget is installed, this command will display the version number. If it’s not installed, you can download the App Installer from the Microsoft Store.

Using Winget

1. Open PowerShell: Open the Windows PowerShell console by right-clicking on the Start button and selecting “PowerShell”.

2. Search for a Package: To search for a specific application:

winget search <package_name>

3. Install a Package: To install a package, use the winget install command followed by the package name.

winget install <package_name>

4. Uninstall a Package: To uninstall a package, use the winget uninstall command followed by the package name.

winget uninstall <package_name>

5. Upgrade a Package: To upgrade a package, use the winget upgrade command followed by the package name.

winget upgrade <package_name> 

What is Version Control?

• Version control is a system for tracking changes to files over time.
  
• It lets you save snapshots of your work, revert to earlier versions, and track who made which changes.
  
• Think of it like the track changes feature in Word or Google Docs, but more powerful and for all kinds of files.
  
• Why it matters: No more files named “Essay_final_v5_FINAL.docx” – version control keeps a history so you always have every version.

flowchart LR
    v1["File Version 1"] --> v2["File Version 2"] --> v3["File Version 3"]

What is Git?

• Git is the most widely used version control tool (VCS) in the world.
• It runs on your computer to track changes in a project (a local repository).
• Git lets you record commits (snapshots of your files) and then sync with a remote server (e.g., GitHub) to share those changes.
• You can experiment on separate branches without affecting the main project, then merge your work when it’s ready.

flowchart LR
    WD[Working Directory] -->|git add| Index[Staging Area] -->|git commit| Repo[Local Repository]
    Repo -->|git push| Remote[GitHub Repository]

(Image source: Git)

In most of the cases, the “Server Computer” is the code repositories. In our case, it is GitHub.

Install Git and GitHub

Homebrew

1. Open Terminal
2. Run the following command to install Homebrew:

brew install git

3. Try the following command to check if Git is installed:

git --version

4. Run the following command to install GitHub CLI:

brew install gh

5. Try the following command to check if GitHub CLI is installed:

gh --version

Winget

1. Open PowerShell
2. Run the following command to install Git:

winget install --id Git.Git

1. Try the following command to check if Git is installed:

git --version

1. Run the following command to install GitHub CLI:

winget install --id GitHub.cli

1. Try the following command to check if GitHub CLI is installed:

gh --version

How to Register a GitHub Account?

• Go to GitHub.com and click Sign Up.
• Choose a username (this will be your handle on GitHub).
• Enter your email (use your Harvard email or EDU email if you want to use the Education benefits) and create a password.
• Verify your account via the email sent by GitHub. -Choose the free plan (it’s sufficient for almost all academic projects).
• Tip: You can skip creating a repository during sign-up – we’ll do that ourselves.

What is Quarto?

Quarto is an open-source scientific and technical publishing system. It:

• Uses a .qmd (Quarto Markdown) file to combine text, code, and outputs.
• Can render to multiple formats (HTML, PDF, Word, reveal.js slides, etc.).
• Supports Python, R, Julia, and more.
• Ideal for reproducible documents, such as articles, presentations, or data analyses.

Install of Quarto CLI

Using the Official Installer:

1. Download Installer: Visit the Quarto Downloads page and download the installer for your OS.
2. Run Installer.
3. Verify Installation: Open Terminal and run:

quarto --version

Install Quarto Extension for VSCode

1. Open VSCode.
2. Click the “Extensions” button on the left sidebar.
3. Search for “Quarto” and click “Install”.

Structure of a .qmd File

A .qmd (Quarto Markdown) file typically has: 1. YAML Header (between — lines):

---
title: "Document Title"
author: "Your Name"
format: html
---

2. Body Content in Markdown:

# Introduction

This is normal text written in Markdown.

When you run:

quarto render your_file.qmd

Quarto processes the .qmd file and produces the output format(s) you specified (e.g., .html, .pdf, etc.).

Practice: Creating a Quarto Document and Pushing to GitHub

This guide will walk you through the process of creating a folder, initializing a Git repository, creating a Quarto (.qmd) file, making initial commits, revising the file, and pushing the changes to a remote repository on GitHub.

Prerequisites:

• Git: Ensure Git is installed on your system. Verify by running git --version in your terminal.
• Quarto: Ensure Quarto is installed. Verify by running quarto --version in your terminal.
• GitHub Account: Ensure you have an account on GitHub.

Instructions:

1. Create a Folder:

   • Open your terminal or command prompt.

   • Navigate to your desired parent directory using the cd command.

   • Create a new folder named my_project:

     mkdir my_project

   • Navigate into the newly created folder:

     cd my_project

2. Initialize a Git Repository:

   • Initialize an empty Git repository in the current directory:

     git init

   • This command creates a .git subdirectory, setting up the necessary files and structures for version control.

3. Create a Quarto (.qmd) File:

   • Open your preferred text editor (e.g., Visual Studio Code).

   • Create a new file named document.qmd with the following content:

     ---
     title: "My First Quarto Document"
     author: "Your Name"
     date: "2025-02-11"
     format: html
     ---
     
     # Introduction
     
     This is my first Quarto document.

   • Save the file in the my_project directory.

4. Make the First Commit:

   • In the terminal, ensure you’re in the my_project directory.

   • Stage the new file for commit:

     git add document.qmd

   • Commit the staged file with a descriptive message:

     git commit -m "Add initial Quarto document"

5. Revise the .qmd File:

   • Open document.qmd in your text editor.

   • Add a new section:

     # Conclusion
     
     This concludes my first Quarto document.

   • Save the changes.

6. Make a Second Commit:

   • Stage the modified file:

     git add document.qmd

   • Commit the changes with an appropriate message:

     git commit -m "Add conclusion section to Quarto document"

7. Push to a Remote Repository on GitHub:
   • Create a Remote Repository:
     • Log in to your GitHub account.
     • Click the “+” icon in the top-right corner and select “New repository”.
     • Name the repository my_project and choose its visibility (public or private).
     • Click “Create repository”.
   • Connect Local Repository to GitHub:

     • In the terminal, add the remote repository:

       git remote add origin https://github.com/your-username/my_project.git

       Replace your-username with your GitHub username.

   • Push Local Changes to GitHub:

     • Push your commits to the remote repository:

       git push -u origin main

       If your local branch is named master, replace main with master.

Notes:

• The git add command stages changes, preparing them for a commit.
• The git commit command records the staged changes in the repository’s history.
• The git push command uploads local repository content to a remote repository.

By following these steps, you’ve successfully created a project, tracked its versions using Git, and published it to GitHub.

References

• Homebrew for MacOS
• Winget for Windows
• Git Documentation
• GitHub Documentation
• Quarto Documentation