Git | Rick's Cookbook

Links#

https://git-scm.com/docs
https://git-scm.com/book/en/v2
https://cli.github.com/manual/gh_pr_create
https://cli.github.com/manual/gh_release_create
https://docs.github.com/en/pull-requests
https://docs.github.com/en/repositories/releasing-projects-on-github

1. Important Points#

Git command mental model:
    working tree:
        local files

    index / stage:
        files prepared for next commit

    local repository:
        local commits

    remote repository:
        origin / upstream on GitHub / GitLab

safety rules:
    git status before destructive commands
    prefer git revert for commits already pushed
    prefer --force-with-lease over --force
    do not reset shared branch unless team agrees

2. Basic#

init repository#

git init

clone repository#

git clone git@github.com:example/order-api.git

check status#

git status

view diff#

git diff

view staged diff#

git diff --cached

add one file#

git add src/orders/service.ts

add all changes#

git add .

add all repository changes from any directory#

git add -A :/

use this when:
    current shell is inside a subdirectory
    you want to stage changes across the whole repository

note:
    :/ means repository root pathspec
    git add . only stages changes under the current directory

commit#

git commit -m "feat: add order create api"

amend last commit#

git commit --amend -m "feat: add order create endpoint"

show commit history#

git log --oneline --decorate --graph --all

show one commit#

git show a1b2c3d

3. Remote#

list remotes#

git remote -v

add remote#

git remote add origin git@github.com:example/order-api.git

change remote URL#

git remote set-url origin git@github.com:example/new-order-api.git

fetch remote#

git fetch origin

fetch all remotes#

git fetch --all --prune

pull current branch#

git pull

pull remote branch into current branch#

git pull origin main

push current branch#

git push

push and set upstream#

git push -u origin feature/order-api

4. Branch#

list local branches#

git branch

list all branches#

git branch -a

create branch#

git branch feature/order-api

switch branch#

git switch feature/order-api

create and switch branch#

git switch -c feature/order-api

create local branch from remote branch#

git switch -c feature/order-api origin/feature/order-api

pull remote branch#

git fetch origin feature/order-api:feature/order-api

rename current branch#

git branch -m feature/order-api-v2

delete local branch#

git branch -d feature/order-api

force delete local branch#

git branch -D feature/order-api

delete remote branch#

git push origin --delete feature/order-api

5. Merge / Rebase#

merge branch into current branch#

git merge feature/order-api

merge main into current branch#

git merge origin/main

abort merge#

git merge --abort

rebase current branch on main#

git rebase origin/main

continue rebase after resolving conflicts#

git rebase --continue

abort rebase#

git rebase --abort

cherry-pick commit#

git cherry-pick a1b2c3d

6. Undo / Rollback#

unstage file#

git restore --staged src/orders/service.ts

discard file changes#

git restore src/orders/service.ts

restore file from main#

git restore --source origin/main src/orders/service.ts

revert one commit#

git revert a1b2c3d

revert merge commit#

git revert -m 1 a1b2c3d

cancel a revert commit#

If git revert already created a new commit, the safest way to cancel it is usually to revert the revert.

git log --oneline
git revert <revert_commit_hash>

Example:

git revert abc1234

This creates another commit that restores the content removed by the previous revert. Use this when the revert commit has already been pushed or shared.

If the revert commit is only local and not pushed yet, you can remove the last commit instead.

Keep the revert changes staged:

git reset --soft HEAD~1

Discard the revert commit and its working tree changes:

git reset --hard HEAD~1

decision:
    already pushed:
        git revert <revert_commit_hash>

    not pushed, want to keep changes staged:
        git reset --soft HEAD~1

    not pushed, want to delete the revert completely:
        git reset --hard HEAD~1

danger:
    reset --hard discards local working tree changes
    check git status before using it

reset last commit but keep changes staged#

git reset --soft HEAD~1

reset last commit and keep changes unstaged#

git reset HEAD~1

reset working tree to remote branch#

git reset --hard origin/main

danger:
    reset --hard discards local working tree changes
    use only after checking git status

find old commit with reflog#

git reflog

restore branch to reflog point#

git reset --hard HEAD@{3}

7. Stash#

stash current changes#

git stash push -m "wip order api"

list stashes#

git stash list

apply latest stash#

git stash apply

apply and drop latest stash#

git stash pop

drop one stash#

git stash drop stash@{0}

clear all stashes#

git stash clear

8. Tag#

git tag

create lightweight tag#

git tag v1.2.0

create annotated tag#

git tag -a v1.2.0 -m "release v1.2.0"

create tag on specific commit#

git tag -a v1.2.0 a1b2c3d -m "release v1.2.0"

push one tag#

git push origin v1.2.0

push all tags#

git push origin --tags

delete local tag#

git tag -d v1.2.0

delete remote tag#

git push origin --delete v1.2.0

9. GitHub PR#

gh auth login

create PR#

gh pr create --base main --head feature/order-api --title "Add order API" --body "Implement order create and query endpoints."

create draft PR#

gh pr create --base main --head feature/order-api --draft --title "WIP order API" --body "Draft for early review."

list PRs#

gh pr list

view PR#

gh pr view 123 --web

checkout PR locally#

gh pr checkout 123

merge PR#

gh pr merge 123 --squash --delete-branch

10. GitHub Release#

create release from tag#

gh release create v1.2.0 --title "v1.2.0" --notes "Release v1.2.0"

create release and generate notes#

gh release create v1.2.0 --generate-notes

upload release asset#

gh release upload v1.2.0 dist/order-api.tar.gz

list releases#

gh release list

delete release#

gh release delete v1.2.0

11. Conflict#

show conflicted files#

git diff --name-only --diff-filter=U

mark resolved file#

git add src/orders/service.ts

finish merge after conflict#

git commit

finish rebase after conflict#

git rebase --continue

12. Worktree#

create worktree for another branch#

git worktree add ../order-api-hotfix hotfix/payment-timeout

list worktrees#

git worktree list

remove worktree#

git worktree remove ../order-api-hotfix

13. Ignore / Cached Files#

staged / index meaning#

staged / index:
    files already added to the next commit
    git commit reads from the index, not directly from the working tree

.gitignore:
    prevents new untracked files from being added accidentally
    does not automatically remove files already tracked or staged

remove ignored build output from index#

Use this when files are already staged/tracked, but should stay on disk and be ignored by Git.

git rm --cached -r envs/uat/ap-northeast-1/sns/builds

Then verify:

git status

result:
    files are removed from Git index
    local files remain on disk
    future git add . will not add them if .gitignore matches

common case:
    .gitignore contains **/builds/**
    zip/json build artifacts were staged before the ignore rule
    git rm --cached removes them from the next commit

Do not use plain rm unless you also want to delete local files.

14. Clean#

preview untracked files to delete#

git clean -nd

delete untracked files#

git clean -fd

danger:
    git clean -fd deletes untracked files
    run git clean -nd first

15. Production Checklist#

before merge:
    git status clean
    tests passed
    branch is up to date
    PR reviewed

before rollback:
    prefer git revert for pushed commits
    record commit hash
    know whether commit is merge commit

before release:
    tag name checked
    release notes generated/reviewed
    artifacts uploaded if needed
    rollback plan exists