Git/GitHub Installation and Usage Guide

# Installation and configuration

# Installing Git

Git homepage

Git is the most widely used distributed version control system.
Linus Torvalds created it in 2005 for Linux kernel development.

On Windows, download the installer from the Git Install for Windows page and follow the setup wizard.
When the installation is complete, close any terminal windows that are already open and open them again.

Git Install for Windows

Starting the setup wizard

Select it if you can, but if you skip it, you can handle it in the initial configuration

Installing..

Installation complete!

On macOS, you can install Git through Xcode Command Line Tools or with Homebrew.
The Git included in Xcode Command Line Tools is a version provided by Apple.
If you need a newer version or want to manage versions easily, Homebrew is the better choice.

To simply install Xcode Command Line Tools, run the following command.
This installs Xcode Command Line Tools, which include Git.

1
xcode-select --install

With Homebrew, you can easily install and manage the latest version of Git.

1
brew install git

Even after you install Git with Homebrew, the Xcode version of Git may still run.
This happens because the Xcode Git path (/usr/bin) is looked up before the Homebrew path (/opt/homebrew/bin) in the $PATH environment variable, and restarting the terminal may give the Homebrew path priority.
You can check the Git path with the which git command.

1
2
3
4
5
which git
# /opt/homebrew/bin/git 

git -v
# git version 2.47.1

# Initial Git configuration

When you use Git for the first time, you need to configure your user information first.
This information is recorded as the author when you create versions (commits).

1
2
git config --global user.name "ParkYoungWoong"
git config --global user.email "thesecon@gmail.com"

For line break (line ending) compatibility between operating systems, also add the following configuration.

1
2
3
4
5
# macOS
git config --global core.autocrlf input

# Windows
git config --global core.autocrlf true

Set the default name of the main branch to main.

1
git config --global init.defaultBranch main

Now check that all the settings were registered correctly.

1
2
3
4
5
6
git config --global --list

# user.name=ParkYoungWoong
# user.email=thesecon@gmail.com
# core.autocrlf=input # true
# init.defaultbranch=main

Here is everything at once.

1
2
3
4
5
git config --global user.name "ParkYoungWoong"
git config --global user.email "thesecon@gmail.com"
git config --global init.defaultBranch main
git config --global core.autocrlf input # macOS
git config --global core.autocrlf true # Windows

# Signing up for GitHub

GitHub is a service run by Microsoft that hosts Git repositories online, so a Git repository that you would otherwise manage only locally can be stored and managed remotely.
This lets you back up your code more safely, collaborate with other developers, and contribute to open source projects.
Even with a free account, you can create unlimited public and private repositories, so GitHub is widely used for everything from personal projects to team collaboration.

You can sign up on the GitHub sign-up page by entering your email, password, and username.
After you sign up and complete email verification, you can start using GitHub.

GitHub sign-up form

# Connecting to GitHub

To communicate with a GitHub remote repository (push, pull, and so on), you need to authenticate.
There are two main authentication methods, HTTPS (credentials) and SSH, and once you set one up, you can use it afterward without entering anything extra.

It is good to set up both methods from the start, but if that is difficult, setting up only the HTTPS method is fine for now.

# HTTPS (credentials)

Credentials come into play when you first push a project to a remote repository (git push) or pull from a remote repository (git pull).
On Windows, installing Git also installs GCM (Git Credential Manager), and the credential helper is set up automatically.
On macOS, if you installed Git with Xcode Command Line Tools, the osxkeychain helper may already be set up.
If you installed it with Homebrew, you can install GitHub CLI and then easily set up credentials through OAuth authentication with the gh auth login command.

1
brew install gh    

In an environment with a credential helper installed, a modal like the one below appears, and you can easily authenticate in the browser with OAuth.

Connect to GitHub

Authorize Git Credential Manager

Authentication Succeeded

If you need to authenticate directly in the terminal instead of through OAuth as shown above, you must use a personal access token (PAT).
Password authentication has not been supported since August 2021.

Log in on the GitHub site and go to the token management page.
If you can't open it directly, get there with the following steps.

1. Log in to GitHub.
2. Click the profile icon in the upper right > Settings.
3. Click Developer settings at the bottom of the left menu.
4. Select Personal access tokens > Tokens (classic).

Once you're there, follow these steps.

1. Click Generate new token > Generate new token (classic).
2. Enter the token information.
   1. In the Note field, enter a token name that helps you identify it.
   2. In the Expiration field, set the token's expiration date.
      If you choose No expiration, the token never expires and you don't need to renew it, but you should be careful for security reasons.
   3. Select the repository access scopes (Select scopes).
      For typical development work (pushing and pulling code, and so on), selecting repo and workflow is enough.
      It is best not to grant more permissions than you need, and you can grant more permissions later if necessary.
3. Click Generate token to create the token.
4. Copy the generated token.

New personal access token (classic)

Once you have completed the steps above, the first time you push a project to a remote repository (git push) later on, you'll be asked for a username and password, as shown below.
For Username, enter your GitHub username, and for Password, paste the token you created above.
For security, what you type in the password field is not shown on the screen, so you may not see anything even after you paste the token.
Just press Enter, and it will be entered correctly.
The information you enter is saved in the credential helper, and you are authenticated automatically after that.

1
2
Username for 'https://github.com': ParkYoungWoong # GitHub username
Password for 'https://ParkYoungWoong@github.com': # Paste the token, then press Enter

If you need to view, edit, or delete saved credentials, use your operating system's credential management tool.
On macOS, search for github.com in the Keychain Access app.
On Windows, find the github.com entry in Control Panel > User Accounts > Credential Manager.

macOS Keychain Access > Checking credentials

Windows Control Panel > User Accounts > Credential Manager

# SSH

With the SSH (Secure Shell) method, you generate a pair of public and private keys and register the public key with GitHub to authenticate.
Unlike a token, you don't need to manage an expiration date, so once it is set up, it is convenient to use.

Run the following command in the terminal.

1
ssh-keygen -t ed25519 -C "GitHub: ParkYoungWoong"

Each option in the command means the following.

• -t: Specifies the key type. rsa is an older key type, and we recommend explicitly using ed25519.
• -C: Adds a comment that identifies the key. You can write anything you like.

Then you'll see the following prompts.
Pressing Enter at each prompt uses the default value, or you can enter a different value if you want.

1
2
3
4
5
6
7
8
# Specify the key name and save path
Enter file in which to save the key (/Users/username/.ssh/id_ed25519): # Enter

# Enter an extra passphrase
Enter passphrase (empty for no passphrase): # Enter

# Confirm the extra passphrase
Enter same passphrase again: # Enter

When it's done, two files are created at the specified path.
The file names come from the key name you specified (id_ed25519 by default), and the public key gets the pub extension.
Files like the following (for example) are created.

• Public key: id_ed25519.pub
• Private key: id_ed25519

Register the public key with GitHub, and never share the private key with anyone!

Now let's register the generated public key with GitHub.
Run the following command in the terminal to copy the generated public key to the clipboard.

1
2
3
4
5
6
7
# macOS
# cat ~/.ssh/key-name.pub | pbcopy
cat ~/.ssh/id_ed25519.pub | pbcopy

# Windows (Git Bash)
# cat ~/.ssh/key-name.pub | clip
cat ~/.ssh/id_ed25519.pub | clip

Log in on the GitHub site and go to the SSH key management page.
If the page link doesn't take you there directly, get there with the following steps.

1. Log in to GitHub.
2. Click the profile icon in the upper right > Settings.
3. Click SSH and GPG keys in the middle of the left menu.

Once you're there, follow these steps.

1. Click New SSH key.
2. Enter the key information.
   1. In the Title field, enter a name that helps you identify it (e.g. my-laptop).
   2. In the Key type field, select Authentication key.
   3. In the Key field, paste the public key you copied.
3. Click Add SSH key to register the key.

Add new SSH Key

Check in the terminal that the SSH key was registered correctly, as follows.
If SSH asks whether you trust the server, as shown below, to confirm that the server you are connecting to is GitHub, enter yes.
Then GitHub's host key is registered as a trusted server.

1
2
3
4
5
ssh -T git@github.com
# The authenticity of host 'github.com (20.200.245.247)' can't be established.
# ED25519 key fingerprint is: SHA256:+DY3wvV6TuJJhbpZsF/zLDA0zMSvHdk4UvC0qU
# This key is not known by any other names.
# Are you sure you want to continue connecting (yes/no/[fingerprint])?

1
2
ssh -T git@github.com
# Hi ParkYoungWoong! You've successfully authenticated, but GitHub does not provide shell access.

If you use the HTTPS address (https://github.com/username/repository.git) when adding a Git remote repository (git remote add), HTTPS authentication is used instead of the SSH key.
To use SSH authentication, you must use the SSH address (git@github.com:username/repository.git).

Checking the HTTPS and SSH addresses in a GitHub repository

# Usage guide

# Understanding the work areas

Git manages files in three main areas, as follows.

The basic workflow of version control is as follows.

1. Edit (create, modify, or delete) files in the project (working directory).
2. Add the changes to the staging area with the git add command.
3. Create a version with the git commit command.

# Understanding file states

Each file under Git version control has one of the following states.

A newly created file starts in the Untracked state.
When you stage it with git add, it becomes Staged, and when you create a version with git commit, it becomes Committed.
If you modify a file that has already been committed, it changes to Modified, and you can record it as a new version again with git add and git commit.

You can check the current state of your files with the git status command, and editors like VS Code show a symbol next to each file name that indicates its state.

File state indicators

# Starting version control

To start Git version control in a project, move to the project folder and run the git init command.
This is called initializing version control, and you only need to run it once per project, at the beginning.

1
2
3
cd my-project
git init
# Initialized empty Git repository in /Users/.../my-project/.git/

Running the command creates a hidden folder named .git inside the project folder.
All version control information (commit history, branches, settings, and so on) is stored in this folder, and the directory that contains it is the Git repository.

Be careful, because deleting this folder erases the entire version history.
On the other hand, you can also delete this folder on purpose to remove the entire version history and start over.

# Checking status

To check the state of the files in the current project, use the git status command.
You can see at a glance which files have been modified, which have been staged, and whether there are new files that are not tracked yet.
It is a good idea to check it often while you work.

1
git status

When you create or modify files in the project, they appear in red text with their change state (Untracked, Modified).

Checking the current status

If you use an editor like VS Code or Cursor, you can check file states in the Source Control panel.

VS Code > Checking the status in Source Control

# Staging

Modifying a file does not create a version right away.
Before you create a version, you first need to add the changed files to the staging area with the git add command.
This is called staging, and it is the step where you decide, "I'll include these changed files in the next version!"

When you stage all changed files, the . you type at the end means the current path, so all changed files in the current path are staged at once.
When you want to pick only specific files to commit, specify the file names directly.

1
2
3
4
5
6
7
8
# Stage a specific file
git add index.html

# Stage several files at once
git add index.html style.css main.js

# Stage all changed files
git add .

If you run git status again after staging as above, the changes to be committed (Changes to be committed) appear in green text.

Staging

In editors like VS Code or Cursor, you can easily stage changes and check them in the Source Control panel.

VS Code > Staging all changes in Source Control

VS Code > Checking staged changes in Source Control

# Comparing before a commit

Creating a version is called a commit.
If you want to check what has changed before you commit, you can use the git diff command.
Added lines are marked with a green + and deleted lines with a red -, so you can easily compare the changes.

1
2
3
4
5
# Check unstaged changes
git diff

# Check staged changes
git diff --staged

Checking changes

In editors like VS Code or Cursor, you can write a message and commit in the Source Control panel.
In VS Code, clicking a changed file in the Source Control panel lets you compare the differences visually.
It is more intuitive than the terminal output, so it is handy to use the editor's features as well.

VS Code > Checking changes in Source Control

# Commit

When your staged changes are ready, you can create a commit with the git commit command.
After the -m option (flag), you can write a message that describes what changed in this version.

1
git commit -m 'Write a commit message..'

It is best to keep commit messages specific and concise, so you can quickly understand each version when you look through the history later.

1
2
3
git commit -m 'Write the login page HTML structure.'
git commit -m 'Fix the header navigation link error.'
git commit -m 'Add a project description to README.'

When you write a commit message, if you press Enter before typing the closing quote ('), it is treated as a simple line break instead of running the command.
This way, you can write multiple lines within a single -m option.

1
2
git commit -m 'Check the email format and password length.
Show an error message when an empty value is submitted.'

If you have many changes and need a more detailed explanation, you can add a body to the commit message.
If you use the -m option twice, the first becomes the subject and the second becomes the body.

1
2
git commit -m 'Add login form validation' -m '- Check the email format and password length.
- Show an error message when an empty value is submitted.'

Or, if you run just git commit without the -m option, a text editor (Vim) opens, and you can freely write a multi-line commit message.

1
git commit

In the editor, the first line is treated as the subject, and everything after one blank line is treated as the body.
The commit is completed when you write the message, save the file, and close the editor; if the default editor is Vim, press Esc -> :wq -> Enter to save and quit.
To quit without saving, press Esc -> :q! -> Enter.
You can remove the comments (lines starting with the # symbol) that are automatically shown at the bottom of the message.

1
2
3
4
5
6
7
8
9
10
Add login form validation

Check the email format and password length.
Show an error message when an empty value is submitted.

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# On branch main
# Changes to be committed:

If the default editor that opens when you run git commit is inconvenient, you can use VS Code or Cursor as the default editor.
Enter the following command in the terminal.
From now on, when you commit, the input opens in that editor, and the commit is completed when you write the message and save it.

1
2
3
4
5
# VS Code
git config --global core.editor "code --wait"

# Cursor
git config --global core.editor "cursor --wait"

In editors like VS Code or Cursor, you can write a message and commit in the Source Control panel.

Writing a message and committing in the VS Code Source Control panel

# Commit history

You can check the commit history you have created so far with the git log command.
The commit ID (commit hash), author, date, and message of each commit are shown, newest first.
A commit ID is a 40-character string that uniquely identifies a commit, and usually the first 7 or so characters are enough to identify it.

1
2
b8c9d0db4e56836a8c1a0b9484375e01168d54d4
b8c9d0d

1
2
3
4
5
6
7
8
9
10
11
12
13
14
git log
# commit b8c9d0d (HEAD -> main)
# Author: ParkYoungWoong <thesecon@gmail.com>
# Date:   Fri Mar 6 14:22:05 2026 +0900
#
#     Write the first page
#
# commit a1b2c3d
# Author: ParkYoungWoong <thesecon@gmail.com>
# Date:   Fri Mar 6 13:15:42 2026 +0900
#
#     Write the login page HTML structure
#
# --- (rest omitted) ---

As the history grows, the output can get long.
With the --oneline option, you can see each commit concisely on a single line, which makes it easy to follow the overall flow.

1
2
3
4
5
git log --oneline
# b8c9d0d Write the first page
# a1b2c3d Write the login page HTML structure
# d4e5f6a Fix the header navigation link error
# 7b8c9d0 Add a project description to README

In editors like VS Code or Cursor, you can check the commit history in the graph at the bottom of the Source Control panel.
Selecting an entry shows the details of that commit.

Checking the commit history in the VS Code Source Control panel

# Reset

Reset is a command that takes you back to a past commit.
When you made a commit by mistake or want to go back to a previous state, you can use the git reset command.
The commits after the point you reset to are deleted and, by default, cannot be recovered, so make sure you clearly understand what you are doing when you use it.

1
2
# git reset <option> <pointer(commit ID)>
git reset --hard HEAD~1

Depending on how you want to handle the changes in the commits you go back past, three options are available.

A common situation is 'you committed, found a problem, and want to go back to the previous state'.
If you plan to delete the latest commit and go back to the one before it, while keeping the changes so you can fix some of them and commit again, use the --soft or --mixed option.

1
2
3
git reset --mixed HEAD~1
# or 
git reset --soft HEAD~1

Or, if you don't need any of the changes in the latest commit and want to start the work over, go ahead and use the --hard option.

1
git reset --hard HEAD~1

HEAD is a pointer to the latest commit, and you can add a number after it to specify how many commits back to go.
HEAD~1 can be shortened to HEAD~, and it means the commit 1 before HEAD.
HEAD~2 means 2 commits before, and HEAD~3 means 3 commits before.

Or you can go back to a specific commit by specifying the commit ID you want, such as 7b8c9d0.
You can find commit IDs with commands such as git log.

1
2
git reset --mixed HEAD~3
git reset --hard 7b8c9d0

# Branches

A branch is a feature that creates an independent workspace.
For example, if you need to fix a bug on the main page while developing a login feature, you can do each task on its own branch.
This way, the tasks don't affect each other, and you can pick (merge) the branches whose work is done.

You can list the branches in the current repository with the git branch command.
The * mark indicates the current branch.

1
2
3
4
5
git branch

# * main
#   feature/login
#   bugfix/header-color

To create a new branch, type the branch name after the git branch command.
It is good to choose an intuitive, concise name that tells you what the work is.

When you create a branch, all the commit history of the current branch is copied as is, and you can start new work.

1
2
# git branch <branch-name>
git branch feature/login

To move to another branch you created, use the git switch command.

1
2
# git switch <branch-name>
git switch feature/login

To create a branch and switch to it in one step, use the -c (create) option.

1
2
# git switch -c <branch-name>
git switch -c feature/login

To delete a branch you no longer need, use the -D option after the git branch command.
You can't delete the current branch, so move to another branch first and then delete it.

1
2
# git branch -D <branch-name>
git branch -D feature/login

Once you have finished the work on a branch and committed it, you can combine those changes into another branch.
This is called a merge: you first move to the branch you want to merge into, and then run the git merge command.
When the merge is complete, the commit history of the other (incoming) branch is applied to the current branch.

1
2
3
4
5
# Move to the branch to merge into
git switch main

# Merge the feature/login branch into the main branch
git merge feature/login

If the same part of the same file was modified on different branches, a conflict can occur when you merge.
When a conflict occurs, Git marks both sides' changes in the file.

1
2
3
4
5
<<<<<<< HEAD
<h1>Hello Git!</h1>
=======
<h2>Hello GitHub!</h2>
>>>>>>> feature/login

Checking a conflict in VS Code

The part from <<<<<<< HEAD to ======= is the content of the current branch (main).
The part from ======= to >>>>>>> is the content of the incoming branch you are merging (feature/login).
Choose the content you want, or combine the two and edit them, and then remove all the conflict markers (<<<<<<<, =======, >>>>>>>).

After you resolve the conflict, stage the file with the git add command and commit it with the git commit command to complete the merge.

1
2
3
# Resolve the conflict on the main branch
git add index.html
git commit -m 'Resolve the conflict between main and feature/login'

# Creating a remote repository

Here is how to create a new remote repository on GitHub.

1. Log in to GitHub.
2. Click the + button in the upper right > New repository.

New repository

3. Enter the repository name (Repository name).
4. Choose whether the repository is public (Public) or private (Private).
5. Click Create repository.

Create a new repository

# Adding a remote repository

Now that you have created the remote repository, you need to register its address in your local repository so you can upload (push) to it.
An alias is a name that refers to the remote repository, and origin is used by convention.
If you want, you can use a different name instead of origin.

1
2
3
4
5
6
7
# git remote add <alias> <remote-repository>

# HTTPS 
git remote add origin https://github.com/username/repository.git

# SSH
git remote add origin git@github.com:username/repository.git

To check that it was registered correctly, run the following command.
The HTTPS or SSH address of the remote repository you registered should appear.

1
2
3
git remote -v
# origin  https://github.com/username/repository.git (fetch)
# origin  https://github.com/username/repository.git (push)

# Pushing code

Uploading the commit history you created locally to a remote repository is called a push.
You do it with the git push command.

1
2
# git push <remote-alias> <branch-name>
git push origin main

If you use the -u option to set the branch to track (upstream), you can push with just git push afterward.
If you change branches, you need to set the upstream again with the -u option.

1
2
3
4
5
# First push
git push -u origin main

# Later pushes
git push

# Pulling code

When you work in another environment, or a teammate changes the code and the remote repository is updated, you need to bring the latest changes from the remote repository to your local machine.
This is called a pull, and you do it with the git pull command.

1
2
# git pull <remote-alias> <branch-name>
git pull origin main

If you set the upstream with the -u option in git push, you can omit the alias and branch name and just type git pull.

1
git pull

Internally, git pull performs the following two steps.
In other words, git pull is a command that fetches the remote changes and automatically merges them as well.

1. git fetch: Brings the latest history from the remote repository to your local machine, but your local files don't change.
2. git merge: Merges the fetched history into the current branch and updates your local files.

# Cloning a repository

To bring a remote repository that already exists on GitHub to your local machine, use the git clone command.
It brings the project contents, commit history, branches, and so on from the remote repository all at once.

1
2
3
4
5
# HTTPS
git clone https://github.com/username/repository.git

# SSH
git clone git@github.com:username/repository.git

By default, a folder with the same name as the repository is created, but you can also specify the folder name yourself.

1
git clone https://github.com/username/repository.git my-project

# Ignoring files in version control

A project has files that don't need version control or must not be shared.
Typical examples are dependency folders like node_modules and environment variable files like .env.
If you write patterns for these files or folders in a .gitignore file, Git automatically ignores them.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# Dependency folders
node_modules/

# Environment variable files
.env
.env.local

# Build output
dist/
build/

# Files generated by the OS
.DS_Store
Thumbs.db

# Workflows

Let's look at some basic workflows that use the commands you have learned so far.
Use the workflow that fits your situation as a reference and adapt it in different ways.

# Starting a new project

This is the process of creating a new project locally and pushing it to GitHub.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# 1. Create the project folder and move into it
mkdir my-project
cd my-project

# 2. Initialize version control
git init

# 3. Create and fill in the file for ignoring files in version control
touch .gitignore

# 4. Work on the project, such as creating and editing files

# 5. Stage
git add .

# 6. First commit
git commit -m 'Create the project.'

# Repeat steps 4-6 until all the work is done

# 7. Create a GitHub remote repository and connect it (HTTPS/SSH)
git remote add origin https://github.com/username/repository.git

# 8. Push to the GitHub remote repository
git push origin main

# Starting from a remote repository

This is the process for joining an existing project that already has a GitHub repository.
For example, this applies when you join a team project a teammate created, or when you continue a work project on your home computer.
When you clone the repository with git clone, you get all the project's files and commit history at once and can start working right away.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 1. Clone the remote repository (HTTPS/SSH)
git clone https://github.com/username/repository.git

# 2. Move into the project folder
cd repository

# 3. Work on the project, such as editing files

# 4. Stage
git add .

# 5. Commit
git commit -m 'Fix a bug'

# 6. Push to the GitHub remote repository
git push

# Everyday workflow

This is the most basic workflow that you repeat often once the initial project setup is done.
Before you start working, you bring in the latest code from the remote (pull), and after working, you commit and push to upload your changes to the remote.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 1. Get the latest code from the remote
git pull

# 2. Work on the project, such as editing files

# 3. Check the status and changes
git status
git diff

# 4. Stage
git add .

# 5. Commit
git commit -m 'Add an intro section'

# 6. Push to the GitHub remote repository
git push

# Workflow with branches

When you add a new feature or fix a bug, working directly on the main branch, main, makes it hard to undo things when a problem occurs.
If you create a separate branch to work on, you can always keep the main branch stable, and if the work goes wrong, you only need to delete that branch.
When the work is done, merge it into the main branch and delete the branch you no longer need.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# 1. Get the latest code
git pull

# 2. Create a new branch to work on and move to it
git switch -c feature/login

# 3. Repeat editing, staging, and committing as many times as needed
git add .
git commit -m 'Write the login form HTML'

git add .
git commit -m 'Add login validation'

# 4. Move to the main branch
git switch main

# 5. Merge the work branch
git merge feature/login

# 6. Push to the remote
git push

# 7. Delete the merged branch
git branch -D feature/login