Git Guide
It is recommended to install Relivator following the detailed instructions in the README.md to feel more confident as you begin learning Git.
It’s true—Git can be complex at first. Consider using resources like this guide, the Git Book, and GitHub Skills to deepen your understanding. The command git commit —help will direct you to information about the git commit
command and its options, so this help command can be beneficial as well. The best way to get comfortable with Git is to use it regularly. Create a small project or use a large web project template like Relivator and experiment with different commands. If you’re ever unsure about something related to Git, refer to this detailed guide to learn more.
Git Initial Setup
By following the details in this guide, you will get a solid start with Git, set up your environment, and use some handy aliases to streamline your workflow. Happy gitting!
Essential Tools
Ensure you have Git installed. It’s also recommended to install: Node.js LTS (Windows/macOS | Linux). Then, run corepack enable pnpm to install pnpm. Additionally, we recommend installing VSCode and GitHub Desktop (Windows/macOS | Linux). If you’re a Windows user, also install PowerShell 7.4+.
Setting Up Your Identity
Before you start creating any commits in Git, you need to set your identity. This is important because your name and email will be added to every commit you make. Since this information is public, use something appropriate.
git config --global user.name "<YOUR_NAME>"git config --global user.email "<YOUR_EMAIL_ADDRESS>"
Checking Your Settings
To see all your Git settings and ensure they are correct, run:
git config --global --list
Git References
Writing good commits is a valuable skill. To learn how to write effective commit messages, refer to the following resources:
- Enhance Your Git Log with Conventional Commits
- Karma Commit Messages
- Semantic Commit Messages
- A Note About Git Commit Messages
- Writing Git Commit Messages
Aliases
Git aliases are shortcuts for longer commands. They can save you a lot of typing and make your workflow more efficient.
Receiving Updates
This alias updates your local repository by pulling the latest changes, rebasing, and updating submodules.
# git downgit config --global alias.down '!git pull --rebase --autostash; git submodule update --init --recursive'
Sending Updates
This alias pushes your changes to the remote repository, including tags.
# git upgit config --global alias.up '!git push; git push --tags'
Undo Staging of One or More Files
Sometimes you stage files by mistake. This alias helps you unstage them.
# git unstage <FILES>git config --global alias.unstage 'reset HEAD --'
Tagging Releases According to Semantic Versioning (SemVer)
Semantic Versioning is a way to tag your releases with meaningful version numbers. These aliases help automate the process.
# git release-majorgit config --global alias.release-major '!latest=$(git describe --abbrev=0 --tags 2>/dev/null); latest=${latest:-v0.0.0}; set -- $(echo $latest | sed -e s/v// -e "s/\./ /g"); major=$1; minor=$2; patch=$3; major=$((major+1)); minor=0; patch=0; next=v$major.$minor.$patch; git tag -a $next -m ""; echo "Previous release:"; echo -n " "; echo $latest; echo "New release:"; echo -n " "; echo $next'
# git release-minorgit config --global alias.release-minor '!latest=$(git describe --abbrev=0 --tags 2>/dev/null); latest=${latest:-v0.0.0}; set -- $(echo $latest | sed -e s/v// -e "s/\./ /g"); major=$1; minor=$2; patch=$3; minor=$((minor+1)); patch=0; next=v$major.$minor.$patch; git tag -a $next -m ""; echo "Previous release:"; echo -n " "; echo $latest; echo "New release:"; echo -n " "; echo $next'
# git release-patchgit config --global alias.release-patch '!latest=$(git describe --abbrev=0 --tags 2>/dev/null); latest=${latest:-v0.0.0}; set -- $(echo $latest | sed -e s/v// -e "s/\./ /g"); major=$1; minor=$2; patch=$3; patch=$((patch+1)); next=v$major.$minor.$patch; git tag -a $next -m ""; echo "Previous release:"; echo -n " "; echo $latest; echo "New release:"; echo -n " "; echo $next'
Ignoring Redundant git
Binary Names in Commands
You can avoid typing git git
by setting up an alias:
# git git status, git git commit, etc.git config --global alias.git '!cd "$GIT_PREFIX" && git'
Displaying Changelog Since Latest Tag
To see the changelog from the latest tag to your current commit, use this alias:
# git changeloggit config --global alias.changelog '!git log $(git describe --abbrev=0 --tags)..HEAD --no-merges --pretty=oneline --abbrev-commit'
Detecting Remnants and Leftovers from Development
Find common leftover markers like TODOs or debug prints in your code:
# git leftovergit config --global alias.leftover '!git grep -P -i -I --untracked "((?<![a-zA-Z0-9])(TODO|FIXME|XXX|console\.log|System\.out|var_dump)(?![a-zA-Z0-9]))|([\t ]+$)"'
Recommendation
Using Your Favorite Editor for Git
You can set your favorite text editor to use with Git for writing commit messages, etc. For example, if you prefer gedit
on Ubun tu:
git config --global core.editor "gedit --wait"
Handling Line Endings Correctly on Windows
Windows and Unix-based systems (like Linux and macOS) handle line endings differently. To avoid issues, configure Git to automatically handle this for you. This will convert line endings to the native Windows format (CRLF) on checkout and back to Unix format (LF) when you push changes.
git config --global core.autocrlf true
Remembering (Caching) Passwords for HTTPS
When you clone repositories over HTTPS, you need to enter a username and password each time, unlike SSH keys. To make Git remember your passwords and make your life easier, use the following commands based on your operating system:
# On Windowsgit config --global credential.helper wincred
# On Ubun tusudo apt-get install libgnome-keyring-devcd /usr/share/doc/git/contrib/credential/gnome-keyringsudo makegit config --global credential.helper /usr/share/doc/git/contrib/credential/gnome-keyring/git-credential-gnome-keyring
# On macOSgit config --global credential.helper osxkeychain
Usage
Update a Forked Repository (Sync with the Original)
-
Add the original repository as a remote (do this only once):
Terminal window git remote add upstream <GIT_URL_OF_ORIGINAL_REPOSITORY> -
Get updates from the original repository and push them to your fork:
Terminal window git pull upstream <BRANCH_NAME>git push origin
Reset a Repository to the Forked Repository’s State
-
Add the original repository as a remote (do this only once):
Terminal window git remote add upstream <GIT_URL_OF_ORIGINAL_REPOSITORY> -
Reset your repository’s state:
Terminal window git remote updategit reset --hard upstream/<BRANCH_NAME>git push origin +<BRANCH_NAME>
Show All Ignored Files for a Repository
To list all ignored files:
git clean -ndX# orgit status --ignored
Get a List of All Remotes for a Repository
To see all remote repositories associated with your local repository:
git remote -v
Remove All Newly Ignored Files
When you’ve added a file to .gitignore
that was previously in the repository, remove it from the repository:
git rm -r --cached .git add .
Changing the URL of a Repository’s Remote
To change the remote URL:
git remote set-url <REMOTE_NAME> <NEW_REMOTE_URL>
Discard Unstaged Changes
To discard all unstaged changes:
git checkout -- .
To discard changes for a specific file or path:
git checkout -- "<PATH_TO_DISCARD_CHANGES_FOR>"
Undo a Commit That Has Already Been Published
Safe method:
git checkout HEAD~1 .git commit -m "Undo some commit"git push <REMOTE_NAME> <BRANCH_NAME>
Dangerous method:
git reset --hard HEAD~1git push -f <REMOTE_NAME> <BRANCH_NAME>
Undo a Local Commit (Not Published Yet)
To keep the changes in your working copy:
git reset --soft HEAD~1
To discard the changes altogether:
git reset --hard HEAD~1
Show Changes Made to the Working Copy
To show unstaged changes only:
git diff
To show staged changes only:
git diff --staged
To show both unstaged and staged changes:
git diff HEAD
Delete a Branch
To delete a branch locally:
git branch -d <BRANCH_NAME>
To delete a branch on the remote:
git push <REMOTE_NAME> :<BRANCH_NAME>
Adding a Description to a Commit
To add a commit message with both a title and a description:
git commit -m "<TITLE>" -m "<DESCRIPTION>"
Remove All Untracked Files and Directories
To preview what will be deleted:
git clean -ndf
To actually delete the files:
git clean -df
Show the Log in a Short Version
To display the commit log in a condensed format:
git log --pretty=oneline --abbrev-commit
Create a Branch
To create a new branch but stay on the current branch:
git branch <NEW_BRANCH_NAME>
To create and switch to a new branch:
git checkout -b <NEW_BRANCH_NAME>
Switch to Another Branch
To switch to another branch:
git checkout <OTHER_BRANCH_NAME>
Tagging Releases
You can mark specific points in your repository’s history by adding tags. Tags are commonly used for releases but can be used for other purposes as well.
To tag the current commit, use the following commands. Replace <TAG_NAME>
with the unique name for the tag (e.g., v1.0.4
for versioning) and <DESCRIPTION>
with a description of the changes (optional).
git tag -a "<TAG_NAME>" -m "<DESCRIPTION>"git push <REMOTE_NAME> --tags
Importing Commits, Pull Requests, and Other Changes via Patch Files
-
Get the patch file for the commit, pull request, or change you want to import. For GitHub pull requests, you can get the patch file by appending
.patch
to the URL of the pull request:Terminal window curl -L https://github.com/<USER>/<REPO>/pull/<ID>.patch -
Apply the patch file using
git apply
:Terminal window curl -L https://github.com/<USER>/<REPO>/pull/<ID>.patch | git apply -
Optionally, make additional changes to the imported code.
-
Commit the changes, mentioning the original author of the patch:
Terminal window git commit --author "<ORIGINAL_AUTHOR_NAME> <<ORIGINAL_AUTHOR_EMAIL>>" -m "<YOUR_COMMIT_MESSAGE>"
Copying a Branch
To create a local copy of an old branch under a new name and push it to the remote:
git checkout -b <NEW_BRANCH_NAME> <OLD_BRANCH_NAME>git push -u <REMOTE_NAME> <NEW_BRANCH_NAME>
Moving a Branch
To rename a branch locally and on the remote:
git checkout -b <NEW_BRANCH_NAME> <OLD_BRANCH_NAME>git push -u <REMOTE_NAME> <NEW_BRANCH_NAME>git branch -d <OLD_BRANCH_NAME>git push origin :<OLD_BRANCH_NAME>
Clearing a Branch and Resetting it to an Empty State
To create a new branch with no history and start fresh:
git checkout --orphan <NEW_BRANCH_NAME>rm -rf ./*# Add your new filesgit add .git commit -m "Initial commit"git push -uf <REMOTE_NAME> <NEW_BRANCH_NAME>
Counting Commits on a Branch
To count the total number of commits on a branch:
git rev-list --count <BRANCH_NAME># Example: git rev-list --count main
To count commits per author:
git shortlog -s -n
Undoing Changes
Undo Git Reset
If you mistakenly ran git reset --hard HEAD^
and lost commits, use git reflog
to find the commit and reset to it:
git refloggit reset 'HEAD@{1}'
Undo Last Commit
To undo the last commit but keep the changes in your working directory:
git reset --soft HEAD~1
Finding Folder Size
To find the size of a folder:
du -hs
Clearing Git History
To remove files from history, use git filter-branch
:
git filter-branch --index-filter 'git rm --cached --ignore-unmatch <pathname>' <commitHASH>
Or use bfg
:
-
Install
bfg
:Terminal window brew install bfg -
Run
bfg
to clean commit history:Terminal window bfg --delete-files *.mp4bfg --replace-text passwords.txtbfg --delete-folders .git -
Remove files:
Terminal window git reflog expire --expire=now --all && git gc --prune=now --aggressive
To replace text, create a passwords.txt
file with the following format:
PASSWORD1 # Replace literal string 'PASSWORD1' with '***REMOVED***' (default)PASSWORD2==>examplePass # Replace with 'examplePass' insteadPASSWORD3==> # Replace with the empty stringregex:password=\w+==>password= # Replace using a regex
Squash Commits
To combine multiple commits into one:
git rebase -i HEAD~<n># orgit rebase -i <COMMIT_HASH>
Undo Your Changes
To discard all changes:
git resetgit checkout .git clean -fdx
Remove node_modules
if Accidentally Checked In
git rm -r --cached node_modules
Amend Your Commit Messages
To change the commit message of the most recent commit:
git commit --amend
Cherry-Picking
To apply a commit from another branch as a new commit:
git cherry-pick <YOUR_COMMIT_HASH>
Branch Management
Rename a Branch
To rename a branch, you can use the following commands:
# Rename the branch from old-name to new-namegit branch -m old-name new-name# Or, if you are on the branch you want to renamegit branch -m new-name
# Delete the old branch on the remote and push the new branchgit push origin :old-name new-name
# Set the upstream branch for the new branchgit push origin -u new-name
Reset Local Repository Branch to Match Remote
To reset your local branch to match the remote repository’s main
branch:
git fetch origingit reset --hard origin/maingit clean -f # Clean local files
Delete All Merged Remote Branches
To delete all remote branches that have already been merged:
git branch -r --merged | grep -v main | sed 's/origin\///' | xargs -n 1 git push --delete origin
Reset to Origin
To reset your local branch to match the remote:
git fetch --all
# Option 1: Reset to main branchgit reset --hard origin/main
# Option 2: Reset to a specific branchgit reset --hard origin/<branch_name>
Get Latest Commit of Repository
To get the latest commit of the repository:
git log -1
Press Q
to exit the log view.
Get Hash from Latest Commit
To get the full hash of the latest commit:
git log -1 --pretty=%H# Output706b92ba174729c6a1d761a8566a74f0a0bf8672
To get the abbreviated hash:
git log -1 --pretty=%h# Output706b92b
To store the hash in a variable:
echo $(git log -1 --pretty=%H)
Tagging for Docker Versioning
Tag the repository and perform a commit:
# Tag the repositorygit tag -a v0.0.1 -m "version v0.0.1"
# Check the taggit describe# Output: v0.0.1
# Perform a commitgit commit -am 'chore: do something'
# Describe againgit describe# Output: v0.0.1-1-g9ba5c76
Git Shortcuts
Set up aliases to simplify common Git commands:
alias gst='git status'alias gcm='git commit -S -am'alias gco='git checkout'alias gl='git pull origin'alias gpom="git pull origin main"alias gp='git push origin'alias gd='git diff | mate'alias gb='git branch'alias gba='git branch -a'alias del='git branch -d'
Getting the GitHub Repository Name and Owner
To get the repository URL and name:
git config --get remote.origin.urlgit ls-remote --get-urlgit remote get-url origin# Output: https://github.com/username/repository.git
basename $(git remote get-url origin) .git# Output: repository
Delete Branch Locally
To delete a branch locally:
git push origin --delete <branch_name>
Clear Local Deleted Branches and Fetch All Other Branches
git remote update --prune
Remove All Local Branches Except the Current One
git branch | grep -v "main" | xargs git branch -D
Sort Branches by Last Commit Date
To list branches sorted by the last commit date:
git fetch --prunegit branch --sort=-committerdate
Commit Management
Git Commit Messages
- feat: A new feature visible to end users.
- fix: A bug fix visible to end users.
- chore: Changes that don’t impact end users (e.g., changes to CI pipeline).
- docs: Changes to documentation.
- refactor: Changes to production code focused on readability, style, or performance.
List Branches that Have Been Merged
git branch --merged
List Branches that Have Not Been Merged
git branch --no-merged
Cleanup and Optimize Repository
To clean up unnecessary files and optimize the local repository:
# Cleanup unnecessary filesgit gc
# Prune all unreachable objects from the object databasegit prune
# Verify the connectivity and validity of objects in the databasegit fsck
# Prune your remote working directorygit remote update --prune
Push Commits with Tags Automatically
git config --global push.followTags true
Restore a File to a Given Commit
To restore a specific file to its state at a given commit:
git restore -s <SHA1> -- <filename>
Useful Git Commands and Techniques
Download Just a Folder from GitHub with Subversion (SVN)
To download a specific folder from a GitHub repository using SVN:
# Replace tree/main with trunk in the URLsvn export https://github.com/alextanhongpin/pkg.git/trunk/authheader
To create an alias for downloading docker-compose
templates:
alias init-db='svn export https://github.com/alextanhongpin/docker-samples/trunk/postgres/docker-compose.yml'
Pre-Commit Hooks
Ensure you have a changelog edited in your current branch. Use a pre-commit hook to enforce this:
#!/bin/bash
if [[ $(git diff develop -- CHANGELOG.md | wc -l) -eq 0 ]]; then echo "Don't forget to add CHANGELOG.md" exit 1fi
Git Rebase Favor Current Branch
To favor the current branch during a rebase:
git rebase -X theirs ${branch}
More info on merge strategies for rebase
Git Post-Checkout Hook
To automate tasks after checking out a branch, use a post-checkout hook:
-
Create and set permissions for the hook:
Terminal window touch .git/hooks/post-checkoutchmod u+x .git/hooks/post-checkout -
Add the following script to
.git/hooks/post-checkout
:#!/bin/bash# Parameters# $1: Ref of previous head# $2: Ref of new head# $3: Whether this is a file checkout (0) or branch checkout (1).# This is a file checkout - do nothingif [ "$3" == "0" ]; then exit; fiBRANCH_NAME=$(git symbolic-ref --short -- HEAD)NUM_CHECKOUTS=$(git reflog --date=local | grep -o ${BRANCH_NAME} | wc -l)# If the refs of the previous and new heads are the same# and the number of checkouts equals one, a new branch has been createdif [ "$1" == "$2" ] && [ ${NUM_CHECKOUTS} -eq 1 ]; thenecho "new branch created"elseecho "switched branch to ${BRANCH_NAME}"fi
Git Checkout a Single File from Main Commit
To revert a file to its state in the main branch:
git checkout $(git rev-parse main) -- path-to-file
Adding New Changes to the Latest Commit
To amend the latest commit with new changes:
git add --allgit commit --amend# Note: You may need to force push if the commit has already been pushedgit push --force
Cleaning a Branch PR
If your branch is messy and you want to clean up the commits:
-
Create a new temporary branch:
Terminal window git checkout -b feature/foo-tmp -
Create a patch file of changes:
Terminal window git diff origin/feature/foo origin/main > out.patch -
Apply the patch to the temporary branch:
Terminal window git apply out.patch -
Clean up and rebase as needed, then delete the old branch:
Terminal window git branch -D feature/foo -
Rename the temporary branch to the original name:
Terminal window git branch -m feature/foo -
Force push the cleaned branch:
Terminal window git push --force feature/foo
Better Push Force
Use git push --force-with-lease
instead of git push --force
for safer forced updates.
Learn more about force-with-lease
Git Fixup
To fix up a previous commit:
-
Create a fixup commit:
Terminal window git commit --fixup <first-commit-hash> -
Rebase to squash the fixup commit:
Terminal window git rebase -i --autosquash --root
Resources
- Relivator Next.js Template
- Theo’s Post
- Martin Heinz’s Blog
- Delight-IM’s Git Knowledge
- Alex Tan Hong Pin’s Cheat Sheet
The Bottom Line
This guide covers various useful Git commands and techniques, inspired by various resources and composed by Reliverse, making it easier for both beginners and advanced users to manage and optimize their repositories.