diff --git a/AGENTS.md b/AGENTS.md index bf46fd6..405f4e8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,7 +5,7 @@ You are an expert software developer handling this repo. ## Persona - You understand the codebase and are capable of explaining the functionality of different components of the repo. - You specialize in spotting cross-platform bugs, for various operating systems. -- Your output: beginner-friendly code explainations, implementation plans, intentional changes, security-oriented reviews that developers can act on, user-facing docs +- Your output: beginner-friendly code explainations, implementation plans, intentional changes, security-oriented reviews that developers can act on. ## Project knowledge **Tech Stack**: Python 3, Click (CLI), Git CLI, GitHub CLI @@ -32,7 +32,6 @@ You are an expert software developer handling this repo. - app/utils/click.py - shared Click helpers (printing, context, prompts) - app/configs/ - config read/write for gitmastery/exercises - app/hooks/ - CLI decorators enforcing repo/exercise context -- docs/ - user documentation and platform guides ## Tools you can use **Run**: @@ -89,7 +88,7 @@ def do_stuff(cfg): **Always**: - Explain the code to be implemented, include reasons for such changes. -- Ask first, before making changes to the code base, adding dependencies, changing packaging/release logic, modifying CI/CD or docs publishing. +- Ask first, before making changes to the code base, adding dependencies, changing packaging/release logic, modifying CI/CD. - When handling files, ensure that the operation works for both Windows and Linux machines **Never**: diff --git a/docs/.gitignore b/docs/.gitignore deleted file mode 100644 index f40fbd8..0000000 --- a/docs/.gitignore +++ /dev/null @@ -1,5 +0,0 @@ -_site -.sass-cache -.jekyll-cache -.jekyll-metadata -vendor diff --git a/docs/404.html b/docs/404.html deleted file mode 100644 index 086a5c9..0000000 --- a/docs/404.html +++ /dev/null @@ -1,25 +0,0 @@ ---- -permalink: /404.html -layout: default ---- - - - -
-

404

- -

Page not found :(

-

The requested page could not be found.

-
diff --git a/docs/Gemfile b/docs/Gemfile deleted file mode 100644 index fe75493..0000000 --- a/docs/Gemfile +++ /dev/null @@ -1,35 +0,0 @@ -source 'https://rubygems.org' -# Hello! This is where you manage which Jekyll version is used to run. -# When you want to use a different version, change it below, save the -# file and run `bundle install`. Run Jekyll with `bundle exec`, like so: -# -# bundle exec jekyll serve -# -# This will help ensure the proper Jekyll version is running. -# Happy Jekylling! -gem 'jekyll', '= 3.10.0' -# This is the default theme for new Jekyll sites. You may change this to anything you like. -gem 'minima', '~> 2.5' -# If you want to use GitHub Pages, remove the "gem "jekyll"" above and -# uncomment the line below. To upgrade, run `bundle update github-pages`. -# gem "github-pages", group: :jekyll_plugins -# If you have any plugins, put them here! -group :jekyll_plugins do - gem 'jekyll-feed', '~> 0.12' -end - -# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem -# and associated library. -platforms :mingw, :x64_mingw, :mswin, :jruby do - gem 'tzinfo', '>= 1', '< 3' - gem 'tzinfo-data' -end - -# Performance-booster for watching directories on Windows -gem 'wdm', '~> 0.1.1', platforms: %i[mingw x64_mingw mswin] - -# Lock `http_parser.rb` gem to `v0.6.x` on JRuby builds since newer versions of the gem -# do not have a Java counterpart. -gem 'http_parser.rb', '~> 0.6.0', platforms: [:jruby] - -gem 'github-pages', "~>\t232", group: :jekyll_plugins diff --git a/docs/_config.yml b/docs/_config.yml deleted file mode 100644 index 6adb6a9..0000000 --- a/docs/_config.yml +++ /dev/null @@ -1,19 +0,0 @@ -title: Git-Mastery -email: woojiahao1234@gmail.com -description: >- # this means to ignore newlines until "baseurl:" - Git-Mastery app installation and usage guide -baseurl: "/app" -url: "https://git-mastery.org" -github_username: git-mastery - -theme: minima -plugins: - - jekyll-feed - -header_pages: - [ - "linux.markdown", - "macos.markdown", - "windows-git-bash.markdown", - "windows-wsl.markdown", - ] diff --git a/docs/index.markdown b/docs/index.markdown deleted file mode 100644 index 77c0e54..0000000 --- a/docs/index.markdown +++ /dev/null @@ -1,30 +0,0 @@ ---- -layout: home ---- - -Welcome to the Git-Mastery app. - -Check out the installation instructions below: - -- [Linux](/app/linux) -- [MacOS](/app/macos) -- [Windows Preferred (WSL)](/app/windows-wsl) -- [Windows (Git Bash)](/app/windows-git-bash) - -Refer to [this guide](/app/update) to update the Git-Mastery app across different OSes. - -This is the overview of the commands available for Git-Mastery: - -|Command|Description| -|-------|-----------| -|`gitmastery [command] help`|Prints the help documentation for each command. Omitting the `[command]` prints the documentation for the app| -|`gitmastery setup`|Setup Git-Mastery for your local machine.| -|`gitmastery check git`|Verify that you have setup Git for Git-Mastery| -|`gitmastery check github`|Verify that you have setup Github and Github CLI for Git-Mastery| -|`gitmastery download `|Downloads the specified exercise to your local machine. For the list of exercises, refer [here](https://git-mastery.org/exercises)| -|`gitmastery verify`|Verify your exercise attempt. Saves the progress made.| -|`gitmastery version`|Get the current version of the Git-Mastery app on your machine.| -|`gitmastery progress sync on`|Enable remote progress tracking.| -|`gitmastery progress sync off`|Disable remote progress tracking.| -|`gitmastery progress show`|Disables your progress made so far and a link to the progress dashboard if you have already enabled sync.| -|`gitmastery progress reset`|Resets the progress for one of your exercises.| diff --git a/docs/linux.markdown b/docs/linux.markdown deleted file mode 100644 index 089b3ba..0000000 --- a/docs/linux.markdown +++ /dev/null @@ -1,163 +0,0 @@ ---- -layout: page -title: Linux ---- - -## Git - -### Verification - -Check if Git is already installed: - -```bash -git version -``` - -If you see something like `git version 2.48.1`, Git is already installed. - -### Git Configuration - -After installing Git, you need to configure it with your identity and preferences. - -#### Set Your Name - -Set the name that will be associated with your Git commits: - -```bash -git config --global user.name "Your Name" -``` - -You can use any name you want if you wish to keep your real name private. This name will be visible in commit history on GitHub. - -#### Set Your Email - -Set the email address for your commits: - -```bash -git config --global user.email "your_email@example.com" -``` - -If you want to keep your email private, GitHub provides a special `noreply` email address. You can set yours up after you setup Github. - -You can find yours by: - -1. Going to GitHub → Settings → Emails -2. Looking for "Keep my email addresses private" -3. Using the provided `noreply` email address (format: `username@users.noreply.github.com`) - -#### Set Default Branch Name - -Configure Git to use `main` as the default branch name for new repositories: - -```bash -git config --global init.defaultBranch main -``` - - -## Git-Mastery - -### Debian/Ubuntu - -Ensure you are running `libc` version 2.38 or newer. - -Then install the following: - -```bash -echo "deb [trusted=yes] https://git-mastery.org/gitmastery-apt-repo any main" | \ - sudo tee /etc/apt/sources.list.d/gitmastery.list > /dev/null -sudo apt install software-properties-common -sudo add-apt-repository "deb https://git-mastery.org/gitmastery-apt-repo any main" -sudo apt update -sudo apt-get install gitmastery -``` - -### Arch - -Install using pacman: - -```bash -sudo pacman -Syu gitmastery-bin -``` - -### Others - -If you are using a Linux distribution that is not yet supported by Git-Mastery, please download the right binary for your architecture from [the latest release.](https://github.com/git-mastery/app/releases/latest) - -Install it to `/usr/bin` to access the binary, the following using version `3.3.0` as an example. - -```bash -install -D -m 0755 gitmastery-3.3.0-linux-arm64 /usr/bin/gitmastery -``` - -## GitHub - -### Create Account - -Create a [new GitHub account](https://docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github) if needed. - -### SSH Setup - -#### 1. Check for Existing SSH Keys - -```bash -ls -al ~/.ssh -``` - -Look for `id_ed25519.pub` or similar. - -#### 2. Create New SSH Key - -```bash -ssh-keygen -t ed25519 -C "your_email@example.com" -``` - -Press Enter to accept all defaults. - -#### 3. Add SSH Key to ssh-agent - -```bash -eval "$(ssh-agent -s)" -ssh-add ~/.ssh/id_ed25519 -``` - -#### 4. Add SSH Key to GitHub - -```bash -cat ~/.ssh/id_ed25519.pub -``` - -Paste the output into GitHub → Settings → SSH and GPG Keys. - -#### 5. Verify SSH Connection - -```bash -ssh -T git@github.com -``` - -## GitHub CLI - -### Installation - -Refer to the [GitHub CLI Linux installation guide](https://github.com/cli/cli/blob/trunk/docs/install_linux.md) for your distribution. - -### Authentication - -```bash -gh auth login -``` - -Choose **SSH** when prompted. - -### Verification - -```bash -gh auth status -``` - -You should see confirmation of your GitHub login using SSH. - -Verify that Github and Github CLI is setup for Git-Mastery: - -```bash -gitmastery check github -``` diff --git a/docs/macos.markdown b/docs/macos.markdown deleted file mode 100644 index 9a4a0cb..0000000 --- a/docs/macos.markdown +++ /dev/null @@ -1,202 +0,0 @@ ---- -layout: page -title: MacOS ---- - -## Homebrew - -Homebrew is a package manager for macOS that makes installing development tools much easier. Most of the tools in this guide can be installed using Homebrew. - -### Verification - -Check if Homebrew is already installed: - -```bash -brew --version -``` - -If you see output like `Homebrew 4.x.x`, Homebrew is installed and you can skip to the Git section. - -### Installation - -Install Homebrew by running this command in Terminal: - -```bash -/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" -``` - -## Git - -### Verification - -Check if Git is already installed: - -```bash -git version -``` - -If you see output like `git version 2.48.1`, Git is installed and you can skip to the GitHub section. - -### Installation - -Install Git using Homebrew: - -```bash -brew install git -``` - -### Git Configuration - -After installing Git, you need to configure it with your identity and preferences. - -#### Set Your Name - -Set the name that will be associated with your Git commits: - -```bash -git config --global user.name "Your Name" -``` - -You can use any name you want if you wish to keep your real name private. This name will be visible in commit history on GitHub. - -#### Set Your Email - -Set the email address for your commits: - -```bash -git config --global user.email "your_email@example.com" -``` - -If you want to keep your email private, GitHub provides a special `noreply` email address. You can set yours up after you setup Github. - -You can find yours by: - -1. Going to GitHub → Settings → Emails -2. Looking for "Keep my email addresses private" -3. Using the provided `noreply` email address (format: `username@users.noreply.github.com`) - -#### Set Default Branch Name - -Configure Git to use `main` as the default branch name for new repositories: - -```bash -git config --global init.defaultBranch main -``` - -## Git-Mastery - -Add the Git-Mastery [tap](https://docs.brew.sh/Taps): - -```bash -brew tap git-mastery/gitmastery -``` - -Install Git-Mastery using Homebrew: - -```bash -brew install gitmastery -``` - -## GitHub - -### Create Account - -Create a [new GitHub account](https://docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github) if you don't have one. - -### SSH Setup - -#### 1. Check for Existing SSH Keys - -```bash -ls -al ~/.ssh -``` - -Look for files named `id_rsa.pub`, `id_ecdsa.pub`, or `id_ed25519.pub`. If you have one, skip to step 4. - -#### 2. Create New SSH Key - -```bash -ssh-keygen -t ed25519 -C "your_email@example.com" -``` -Press Enter to accept all defaults (including empty passphrase). - -#### 3. Add SSH Key to ssh-agent - -Start the ssh-agent: - -```bash -eval "$(ssh-agent -s)" -``` - -Configure SSH (for macOS Sierra 10.12.2 or later): - -```bash -touch ~/.ssh/config -``` - -Add this to your `~/.ssh/config` file: - -``` -Host github.com - AddKeysToAgent yes - UseKeychain yes - IdentityFile ~/.ssh/id_ed25519 -``` - -Add your SSH key: - -```bash -ssh-add --apple-use-keychain ~/.ssh/id_ed25519 -``` - -#### 4. Add SSH Key to GitHub - -Copy your public key to clipboard: - -```bash -pbcopy < ~/.ssh/id_ed25519.pub -``` - -1. Go to GitHub → Settings → SSH and GPG keys → New SSH key -2. Give it a name and paste your public key -3. Save - -#### 5. Verify SSH Connection - -```bash -ssh -T git@github.com -``` - -Type `yes` when prompted, and you should see a message with your username. - -## GitHub CLI - -### Installation - -With Homebrew installed, installing GitHub CLI is simple: - -```bash -brew install gh -``` - -### Authentication - -```bash -gh auth login -``` - -Select SSH when prompted (since you set up SSH above). - -### Verification - -```bash -gh auth status -``` - -You should see confirmation that you're logged in with SSH protocol. - -Verify that Github and Github CLI is setup for Git-Mastery: - -```bash -gitmastery check github -``` diff --git a/docs/update.markdown b/docs/update.markdown deleted file mode 100644 index aa08657..0000000 --- a/docs/update.markdown +++ /dev/null @@ -1,30 +0,0 @@ ---- -layout: page -title: Update your app ---- - -Use `git version` to check out your app's version and find the latest version [here](https://github.com/git-mastery/app/releases/latest) - -## Windows - -Download the [latest version](https://github.com/git-mastery/app/releases/latest) of the `.exe` and update where it was originally located. - -## MacOS - -```bash -brew update && brew upgrade gitmastery -``` - -## Linux - -### Debian/Ubuntu - -```bash -sudo apt-get install --only-upgrade gitmastery -``` - -### Arch - -```bash -sudo pacman -S gitmastery-bin -``` diff --git a/docs/windows-git-bash.markdown b/docs/windows-git-bash.markdown deleted file mode 100644 index ff5a0d5..0000000 --- a/docs/windows-git-bash.markdown +++ /dev/null @@ -1,153 +0,0 @@ ---- -layout: page -title: Windows (Git Bash) ---- - -## Git - -### Verification - -Check if Git is already installed: - -```bash -git version -``` - -If you see output like `git version 2.48.1`, Git is installed and you can skip to the GitHub section. - -### Installation - -Download the Git installer from the [official Git website](https://git-scm.com/downloads/win). -Run the installer and make sure to select the option to install **Git Bash** when prompted. - -### Git Configuration - -After installing Git, configure your identity and preferences: - -#### Set Your Name - -```bash -git config --global user.name "Your Name" -``` - -You can use a pseudonym if you want to keep your real name private. - -#### Set Your Email - -```bash -git config --global user.email "your_email@example.com" -``` - -To keep your email private, GitHub offers a `noreply` email. Set this up by going to: - -1. GitHub → Settings → Emails -2. Enable **"Keep my email address private"** -3. Use the provided `username@users.noreply.github.com` - -#### Set Default Branch Name - -```bash -git config --global init.defaultBranch main -``` - -## Git-Mastery - -1. Download the `.exe` file from [the latest release](https://github.com/git-mastery/app/releases/latest). -2. Add the `.exe` to your `PATH` following [this guide](https://www.eukhost.com/kb/how-to-add-to-the-path-on-windows-10-and-windows-11/). - -## GitHub - -### Create Account - -Create a [new GitHub account](https://docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github) if you don't have one. - -### HTTPS Setup - -By default, Github will use HTTPS, which will prompt for your Github username and Personal Access Token (PAT) every time. - -> [!INFO] -> If you intend to use HTTPS, you can skip the "SSH Setup" section. - -#### 1. Setup PAT - -Github no longer supports account passwords for HTTPS, you will need to setup a PAT. - -1. Go to Github → Settings -> Developer settings -> Personal Access Tokens -> Tokens (classic) -2. Click "Generate new token", and set the expiration and scopes (minimum scope is `repo`) -3. Copy the token and store it safely - -#### 2. Using the PAT - -When you are prompted to enter your Github credentials, use your Github username and PAT as the password. - -### SSH Setup - -#### 1. Check for Existing SSH Keys - -```bash -ls -al ~/.ssh -``` - -Look for files like `id_ed25519.pub`. - -#### 2. Create New SSH Key - -```bash -ssh-keygen -t ed25519 -C "your_email@example.com" -``` - -#### 3. Add SSH Key to ssh-agent - -In a **PowerShell (Admin)** window: - -```powershell -Get-Service -Name ssh-agent | Set-Service -StartupType Manual -Start-Service ssh-agent -ssh-add ~/.ssh/id_ed25519 -``` - -#### 4. Add SSH Key to GitHub - -Copy your public key: - -```bash -cat ~/.ssh/id_ed25519.pub -``` - -Then add it to GitHub → Settings → SSH and GPG Keys. - -#### 5. Verify SSH Connection - -```bash -ssh -T git@github.com -``` - -Say `yes` when prompted, and you should see a welcome message with your username. - -## GitHub CLI - -### Installation - -Download the `.msi` installer from the [GitHub CLI releases page](https://github.com/cli/cli/releases). - -### Authentication - -```bash -gh auth login -``` - -Choose SSH when prompted. - -### Verification - -```bash -gh auth status -``` - -You should see confirmation that you're logged in with SSH protocol. - -Verify that Github and Github CLI is setup for Git-Mastery: - -```bash -gitmastery check github -``` diff --git a/docs/windows-wsl.markdown b/docs/windows-wsl.markdown deleted file mode 100644 index fca2081..0000000 --- a/docs/windows-wsl.markdown +++ /dev/null @@ -1,212 +0,0 @@ ---- -layout: page -title: Windows (WSL) ---- - -We recommend using WSL over Git Bash for Git-Mastery on Windows. - -## WSL Installation - -To get started with Windows Subsystem for Linux (WSL), you'll need to enable the feature and install a Linux distribution. - -### Enable WSL - -Open PowerShell or Windows Command Prompt as an administrator and run the following command: - -```ps1 -wsl --install -``` - -This command will enable the necessary optional components, download the latest Linux kernel, set WSL 2 as your default, and install **Ubuntu** by default. Ubuntu is generally recommended for its wide community support and extensive package availability. - -```ps1 -wsl --install -d Ubuntu-24.04 -``` - -If you want to install a different distribution, you can specify it: - -```ps1 -wsl --install -d -``` - -Once installed, launch the distribution from the Start Menu. The first time you launch it, you'll be prompted to create a username and password for your new Linux environment. - -## Git - -### Verification - -Check if Git is already installed within your WSL distribution: - -```bash -git version -``` - -If you see something like `git version 2.48.1`, Git is already installed. - -### Installation - -If Git is not installed, follow the instructions for your specific WSL distribution: - -#### Ubuntu - -```bash -sudo apt update -sudo apt install git -``` - -#### Arch - -```bash -sudo pacman -Syu git -``` - -### Git Configuration - -After installing Git, you need to configure it with your identity and preferences. These configurations will be specific to your WSL environment. - -#### Set Your Name - -Set the name that will be associated with your Git commits: - -```bash -git config --global user.name "Your Name" -``` - -You can use any name you want if you wish to keep your real name private. This name will be visible in commit history on GitHub. - -#### Set Your Email - -Set the email address for your commits: - -```bash -git config --global user.email "your_email@example.com" -``` - -If you want to keep your email private, GitHub provides a special `noreply` email address. You can set yours up after you setup Github. - -You can find yours by: - -1. Going to GitHub → Settings → Emails -2. Looking for "Keep my email addresses private" -3. Using the provided `noreply` email address (format: `username@users.noreply.github.com`) - -#### Set Default Branch Name - -Configure Git to use `main` as the default branch name for new repositories: - -```bash -git config --global init.defaultBranch main -``` - -## Git-Mastery - -Follow the installation instructions for your specific WSL distribution, as Git-Mastery will be installed directly within your Linux environment. - -### Ubuntu - -Ensure you are running `libc` version 2.38 or newer. - -Then install the following: - -```bash -echo "deb [trusted=yes] https://git-mastery.org/gitmastery-apt-repo any main" | \ - sudo tee /etc/apt/sources.list.d/gitmastery.list > /dev/null -sudo apt install software-properties-common -sudo add-apt-repository "deb https://git-mastery.org/gitmastery-apt-repo any main" -sudo apt update -sudo apt-get install gitmastery -``` - -### Arch - -Install using `pacman`: - -```bash -sudo pacman -Syu gitmastery-bin -``` - -### Others - -If you are using a Linux distribution in WSL that is not yet supported by Git-Mastery, please download the right binary for your architecture from [the latest release.](https://github.com/git-mastery/app/releases/latest) - -Install it to `/usr/bin` to access the binary, the following using version `3.3.0` as an example. - -```bash -install -D -m 0755 gitmastery-3.3.0-linux-arm64 /usr/bin/gitmastery -``` - -## GitHub - -### Create Account - -Create a [new GitHub account](https://docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github) if needed. - -### SSH Setup - -Perform these steps within your WSL distribution. - -#### 1. Check for Existing SSH Keys - -```bash -ls -al ~/.ssh -``` - -Look for `id_ed25519.pub` or similar. - -#### 2. Create New SSH Key - -```bash -ssh-keygen -t ed25519 -C "your_email@example.com" -``` - -Press Enter to accept all defaults. - -#### 3. Add SSH Key to ssh-agent - -```bash -eval "$(ssh-agent -s)" -ssh-add ~/.ssh/id_ed25519 -``` - -#### 4. Add SSH Key to GitHub - -```bash -cat ~/.ssh/id_ed25519.pub -``` - -Paste the output into GitHub → Settings → SSH and GPG Keys. - -#### 5. Verify SSH Connection - -```bash -ssh -T git@github.com -``` - -## GitHub CLI - -### Installation - -Refer to the [GitHub CLI Linux installation guide](https://github.com/cli/cli/blob/trunk/docs/install_linux.md) for your specific WSL distribution (Ubuntu or Arch). - -### Authentication - -```bash -gh auth login -``` - -Choose **SSH** when prompted. - -### Verification - -```bash -gh auth status -``` - -You should see confirmation of your GitHub login using SSH. - -Verify that Github and GitHub CLI is setup for Git-Mastery: - -```bash -gitmastery check github -``` -