Git Operations Reference

git merge feature-a feature-b

git cat-file -p HEAD

# Purpose: Unstage modifications for specified paths
# Result: Restores the corresponding content in the index to HEAD's version, keeping the working directory files unchanged
git restore --staged <pathspec>...
# Example 1: Unstage README.md, but keep the file modifications
git restore --staged README.md

# Purpose: Reapply commits unique to the current branch onto a new base
# Conditions: The current branch is the one to be rewritten; index and tracked files have no uncommitted modifications; related commits have not been shared or rewrite has been coordinated
# Result: Rebuilds current branch's commits after <upstream>, and points current branch to the new commit sequence; <upstream> remains unchanged
git rebase <upstream>
# Example 1: Current branch is feature/example, reapply its unique commits after main
git rebase main

# Purpose: Separately specify new base, commit selection boundary, and branch to rewrite
# Conditions: Index and tracked files have no uncommitted modifications; <branch> is not used by other worktrees; related commits have not been shared or rewrite coordinated
# Result: Selects commits unique to <branch> relative to <upstream>, reapplies them onto <new-base>, then points <branch> to the new sequence
git rebase --onto <new-base> <upstream> <branch>
# Example 1: Reapply commits from topic/example unique relative to integration onto main
git rebase --onto main integration topic/example

# Purpose: Adjust commit order, modify commit messages, squash or drop commits
# Conditions: Index and tracked files have no uncommitted modifications; pending commits not yet shared or rewrite coordinated
# Result: Opens a to-do list of commits arranged from oldest to newest, and recreates commits after <upstream> according to the saved content
git rebase -i <upstream>
# Example 1: Interactively tidy up the last 5 commits of the current branch
git rebase -i HEAD~5

# Purpose: Perform rebase when local modifications exist
# Conditions: No unresolved merge conflicts exist; ordinary untracked files must not block Git writes; related commits not shared or rewrite coordinated
# Result: Creates a temporary stash before rebasing, reapplies it after rebasing finishes; reapplying may still produce conflicts
git rebase --autostash <upstream>
# Example 1: Temporarily save local modifications, rebase current branch to main, then reapply these modifications
git rebase --autostash main

# Purpose: Recreate original merge structure during rebase
# Conditions: Index and tracked files have no uncommitted modifications; related commits not shared or rewrite coordinated
# Result: Reapplies ordinary commits on new base and attempts to recreate merge commits; previous manual conflict resolutions may need to be handled again
git rebase --rebase-merges <upstream>
# Example 1: Rebase current branch to main, and recreate its merge structure
git rebase --rebase-merges main

# Purpose: Continue rebase after resolving conflicts or finishing interactive edits
# Conditions: Rebase is paused; conflicts are resolved and staged with git add, or current editing is complete
# Result: Completes the rebuilding of the current commit and continues processing remaining commits
git rebase --continue

# Purpose: Skip currently un-applicable commit and continue rebase
# Conditions: Rebase is paused, and it is confirmed the new history doesn't need the current commit's modifications
# Result: The current commit will not enter the rebuilt history, rebase continues processing subsequent commits
git rebase --skip

# Purpose: Cancel a paused rebase
# Conditions: Rebase has started but not yet finished
# Result: Abandons the unfinished rebase, and restores to the state before the rebase started
git rebase --abort

# Purpose: View the list of stashes in the current repository
git stash list

# Purpose: Temporarily save modifications to tracked files
# Conditions: Index must not contain unresolved merge conflicts
# Result: Creates a stash, saving staged and unstaged modifications, and returns corresponding files to HEAD state
git stash push -m <message>
# Example 1: Save current modifications to tracked files, and label the record as wip: example
git stash push -m "wip: example"

# Purpose: Save modifications to tracked files and untracked files simultaneously
# Conditions: Index must not contain unresolved merge conflicts
# Result: Creates a stash, saving staged, unstaged modifications, and untracked files; then returns tracked files to HEAD, and removes saved untracked files from working tree; ignored files remain unchanged
git stash push -u -m <message>
# Example 1: Save current modifications and untracked files, but not ignored files
git stash push -u -m "wip: example"

# Purpose: Only save modifications in specified paths
# Conditions: Index must not contain unresolved merge conflicts
# Result: Only writes modifications matching paths to stash and reverts them, other paths remain unchanged
git stash push -m <message> -- <pathspec>...
# Example 1: Only save modifications in docs/ and README.md
git stash push -m "wip: docs" -- docs/ README.md

# Purpose: View diff statistics for a specific stash
# Result: Shows diff stats of the stash relative to its base commit when created, changes no states
git stash show --stat <stash>
# Example 1: View diff stats of the newest stash
git stash show --stat stash@{0}

# Purpose: View full patch of a specific stash
# Result: Shows the full diff of the stash relative to its base commit when created, changes no states
git stash show -p <stash>
# Example 1: View full patch of the newest stash
git stash show -p stash@{0}

# Purpose: Apply a specific stash, while keeping the record
# Conditions: Working directory must match index
# Result: Applies recorded modifications to current state; may produce conflicts, but won't delete the stash
git stash apply <stash>
# Example 1: Apply newest stash, keeping the record
git stash apply stash@{0}

# Purpose: Apply a specific stash, and delete the record upon success
# Conditions: Working directory must match index
# Result: Applies recorded modifications to current state; deletes stash on success, keeps it on conflict
git stash pop <stash>
# Example 1: Apply newest stash, and delete the record upon success
git stash pop stash@{0}

# Purpose: Create a branch from the base commit when the stash was created and apply modifications
# Conditions: <new-branch> must not exist, current local modifications must not prevent switching to the stash's base commit
# Result: Creates and switches to new branch, applies stash; deletes stash record upon success
git stash branch <new-branch> <stash>
# Example 1: Create recovery/example branch and apply newest stash
git stash branch recovery/example stash@{0}

# Purpose: View all worktrees associated with the repository
git worktree list

# Purpose: Create a new branch from a specified starting point, and create a worktree for it
# Conditions: Working directory where command is executed can be clean or unclean
# Result: Creates a new branch starting from <commit-ish>, and establishes a worktree for it at <path>
git worktree add -b <new-branch> <path> [<commit-ish>]
# Example 1: Create hotfix/example branch starting from origin/main, establish worktree in adjacent project-hotfix/
git worktree add -b hotfix/example ../project-hotfix origin/main
# Example 2: Create feature/example branch starting from current HEAD, establish worktree in adjacent project-feature/
git worktree add -b feature/example ../project-feature
# Example 3: Create hotfix/v1.2.1 branch starting from v1.2.0, establish worktree in adjacent project-hotfix-v1.2.1/
git worktree add -b hotfix/v1.2.1 ../project-hotfix-v1.2.1 v1.2.0

# Purpose: Create a worktree for an existing local branch
# Conditions: Working directory can be clean or unclean; <branch> is not used by other worktrees
# Result: Establishes a worktree using <branch> at <path>; uncommitted modifications and staged content from original working directory are not copied over
git worktree add <path> <branch>
# Example 1: Establish a worktree using branch release/1.x in adjacent project-release/
git worktree add ../project-release release/1.x

# Purpose: Create a temporary worktree not bound to a branch for a specific version, used for inspecting old versions, testing, or executing bisect
# Conditions: Working directory where command is executed can be clean or unclean
# Result: Establishes worktree at <path>, its HEAD points directly to specified commit in detached HEAD state; original working directory state remains unchanged
git worktree add --detach <path> <commit-ish>
# Example 1: Directly use abbreviated commit ID to establish temp worktree pointing to 9f3a2c1 in adjacent project-inspect-commit/
git worktree add --detach ../project-inspect-commit 9f3a2c1
# Example 2: Establish temp worktree pointing to commit referenced by tag v1.2.0 in adjacent project-inspect-tag/
git worktree add --detach ../project-inspect-tag v1.2.0

# Purpose: Remove a linked worktree no longer needed, but keep its branch and commits
# Conditions: Working directory can be clean or unclean; target must be clean, unlocked, and have no submodules
# Result: Deletes <worktree> working directory and its management records, does not delete corresponding branch and commits
git worktree remove <worktree>
# Example 1: Remove adjacent project-hotfix/ worktree
git worktree remove ../project-hotfix

# Purpose: Preview invalid worktree management records that can be cleaned up
# Conditions: Working directory can be clean or unclean; needs to be executed within any worktree of the repository
# Result: Lists management records where working directory no longer exists and meets cleanup conditions, without actually deleting
git worktree prune --dry-run

# Purpose: Clean up invalid worktree management records
# Conditions: Working directory can be clean or unclean; needs to be executed within any worktree of the repository
# Result: Deletes management records where working directory no longer exists and meets cleanup conditions, doesn't delete existing worktrees, branches, or commits
git worktree prune

# Purpose: Repair invalidated associations after manually moving main worktree or linked worktree
# Conditions: Working directories of execution and target can be clean or unclean; new path must be provided if moving linked worktree
# Result: Re-establishes bidirectional association between repository management directory and corresponding worktree, doesn't change files, branches, or commits
git worktree repair [<path>...]
# Example 1: Repair a linked worktree already manually moved to ../project-hotfix/
git worktree repair ../project-hotfix

# Purpose: Introduce an existing commit into the current branch
# Conditions: Current working tree must be clean
# Result: Applies modifications introduced by target commit, and creates a new commit on current branch
git cherry-pick <commit-ish>
# Example 1: Introduce commit 9f3a2c1 into current branch
git cherry-pick 9f3a2c1

# Purpose: Apply an existing commit's modifications, but don't immediately create a commit
# Conditions: Index must not contain unresolved merge conflicts; existing local modifications must not be overwritten by target modifications
# Result: Writes target modifications to working directory and index, HEAD and current branch remain unchanged
git cherry-pick --no-commit <commit-ish>
# Example 1: Apply modifications of commit 9f3a2c1, check or adjust before manually committing
git cherry-pick --no-commit 9f3a2c1

# Purpose: Revert modifications introduced by an ordinary commit
# Conditions: Current working tree must be clean
# Result: Creates a new commit that undoes the target commit, original commit and existing history remain unchanged
git revert <commit-ish>
# Example 1: Revert commit 9f3a2c1 with a new commit
git revert 9f3a2c1

# Purpose: Revert a merge commit; due to multiple parents, -m must specify which mainline to keep
# Conditions: Current working tree must be clean; target is a merge commit; <parent-number> corresponds to one of its parents
# Result: Reverses the changes of the merge relative to that parent commit; does not revert that parent, nor delete the original merge commit
git revert -m <parent-number> <merge-commit>
# Example 1: Check parent order first, then keep the mainline represented by the first parent and revert the merge
git show --no-patch --pretty=raw 6d8f2a1
git revert -m 1 6d8f2a1
# Note: Revert only reverses content, original merge relationship still exists; merging again won't automatically restore the reverted content

# Purpose: Move current branch, while keeping contents in index and working directory
# Conditions: Index must not contain unresolved merge conflicts
# Result: Current branch or detached HEAD moved to target commit; index and working directory remain unchanged
git reset --soft <commit-ish>
# Example 1: Retract current commit, while keeping its modifications in a staged state
git reset --soft HEAD^

# Purpose: Move current branch and cancel staged state after target commit
# Conditions: Current working tree can be clean or unclean
# Result: Current branch or detached HEAD moved to target commit, index reset to target content, working directory remains unchanged
git reset --mixed <commit-ish>
# Example 1: Retract current commit and cancel staged state of its modifications, but keep file modifications
git reset --mixed HEAD^

# Purpose: Make current branch, index, and tracked files all return to specified commit
# Conditions: Current working tree can be clean or unclean
# Result: Current branch or detached HEAD moved to target commit; index and tracked files overwritten by target content, blocking untracked paths might also be deleted
git reset --hard <commit-ish>
# Example 1: Retreat current branch to previous commit, and discard uncommitted modifications in index and working directory
git reset --hard HEAD^

# Purpose: View update records for HEAD or specified reference
# Result: Shows reflog position, commit ID, and operation description in reverse chronological order, changes no references
git reflog show [-n <count>] [--date=<format>] [<ref>]
# Example 1: Show recent 10 update records of HEAD in local time
git reflog show -n 10 --date=local HEAD
# Example 2: Show recent 5 update records of main
git reflog show -n 5 main

# Purpose: List references in current repository that have a reflog
# Result: Outputs reference names, changes no reflog or references
git reflog list

# Purpose: Check if specified reference has a reflog
# Result: Returns exit status 0 if exists, non-zero otherwise; does not output reflog content
git reflog exists <ref>
# Example 1: Check if local main branch has a reflog
git reflog exists refs/heads/main

# Purpose: Inspect an old position recorded in reflog
# Conditions: Specified record has not expired, and the Git object it points to still exists
# Result: Shows the commit corresponding to that position and its patch, does not move any references
git show <ref>@{<specifier>}
# Example 1: Inspect the commit HEAD pointed to two moves ago
git show HEAD@{2}

# Purpose: Retain a commit found in reflog as a new branch
# Conditions: Specified record and its commit still exist; <new-branch> must not exist
# Result: Creates a new branch pointing to that commit, does not switch branches, does not move existing references
git branch <new-branch> <ref>@{<specifier>}
# Example 1: Retain the commit HEAD pointed to two moves ago as rescue/example
git branch rescue/example HEAD@{2}

# Purpose: Create a self-contained bundle
# Conditions: Execution working directory can be clean or unclean; can pack all references or specified branch
# Result: Writes self-contained repository data into <file>
git bundle create <file> <git-rev-list-args>
# Example 1: Pack all references in current repository into project.bundle
git bundle create project.bundle --all
# Example 2: Only pack history of main branch into main.bundle
git bundle create main.bundle main

# Purpose: Create an incremental bundle
# Conditions: Current repository must possess the specified new commits and base commits
# Result: Writes only the history from <base> to <new-commit> into <file>
git bundle create <file> <base>..<new-commit>
# Example 1: Create an incremental bundle from v1.0.0 up to main
git bundle create update.bundle v1.0.0..main

# Purpose: Verify if a bundle is valid and complete
# Conditions: Execute within a Git repository; when verifying incremental bundles, should execute in receiving repository
# Result: Checks file integrity, and lists prerequisite commits missing in current repository; imports no objects
git bundle verify <file>
# Example 1: Verify project.bundle
git bundle verify project.bundle

# Purpose: Create new repository from a self-contained bundle
# Conditions: <file> must be a bundle with no missing prerequisite commits, <directory> must not be an existing non-empty directory
# Result: Creates new repository in <directory> containing bundle history
git clone <file> <directory>
# Example 1: Create project/ repository from project.bundle
git clone project.bundle project

# Purpose: View references provided by a bundle
# Result: Shows readable references and their commit IDs within, imports no objects
git ls-remote <file>
# Example 1: View references provided by project.bundle
git ls-remote project.bundle

# Purpose: Fetch specified reference from bundle
# Conditions: Execute in receiving repository; repository must possess bundle's prerequisite commits
# Result: Imports required objects, and updates local reference according to refspec
git fetch <file> <source-ref>:<destination-ref>
# Example 1: Fetch main branch of project.bundle as bundle/main remote-tracking reference
git fetch project.bundle refs/heads/main:refs/remotes/bundle/main

# Purpose: Export specified version as a source package
# Conditions: Execution working directory can be clean or unclean
# Result: Writes files in specified version to <output>, and prepends <prefix>/ to paths inside the package
git archive --format=<format> --prefix=<prefix>/ -o <output> <tree-ish>
# Example 1: Export v1.2.0 tag as project-1.2.0.tar.gz
git archive --format=tar.gz --prefix=project-1.2.0/ -o project-1.2.0.tar.gz v1.2.0

# Purpose: Specify bad and good boundaries and start bisection
# Conditions: Both boundaries have been verified; working directory can safely switch commits
# Result: Records HEAD before starting, and switches to first candidate commit
git bisect start <bad> <good>
# Example 1: Start bisect between current commit and v1.0.0
git bisect start HEAD v1.0.0

# Purpose: Mark current candidate commit as good/normal
# Conditions: bisect in progress, and current commit confirmed good
# Result: Updates good boundary, and switches to next candidate or reports result
git bisect good

# Purpose: Mark current candidate commit as bad/abnormal
# Conditions: bisect in progress, and current commit confirmed bad
# Result: Updates bad boundary, and switches to next candidate or reports result
git bisect bad

# Purpose: Skip candidate commit that cannot currently be reliably judged
# Conditions: bisect in progress, and current commit cannot be classified as good or bad
# Result: Selects other candidate commit; may not determine unique result if skips are near boundary
git bisect skip

# Purpose: End bisection
# Conditions: bisect in progress
# Result: Clears bisection state, and restores branch or commit position before bisection started
git bisect reset

# Purpose: Automatically test candidate commits with specified command
# Conditions: bisect in progress; command can return stable exit status as agreed
# Result: Repeatedly tests and marks candidate commits, until boundary located or bisect aborted
git bisect run <command> [<argument>...]
# Example 1: Automatically test candidates using script outside repository
git bisect start HEAD v1.0.0
git bisect run ../test-regression.sh
git bisect reset

# Purpose: Output operation records of current bisection process
# Conditions: bisect in progress
# Result: Outputs records for inspection, saving, or replay usage, changes no bisect state
git bisect log
# Example 1: Save records to a file outside repository
git bisect log > ../bisect.log

# Purpose: Restore bisect progress from existing records
# Conditions: <log-file> is valid record generated by git bisect log; working directory can safely switch commits
# Result: Replays start, good, bad, and skip operations from records
git bisect replay <log-file>
# Example 1: Restore bisect progress from saved records
git bisect reset
git bisect replay ../bisect.log

# Purpose: Start scheduled maintenance for current repository
# Conditions: Execution working directory can be clean or unclean; available scheduler exists in OS
# Result: Registers current repository, sets to incremental if no strategy configured, turns off auto-maintenance triggered by regular Git commands, and creates or updates user-level background schedule
git maintenance start [--scheduler=<scheduler>]
# Example 1: Let Git automatically choose scheduler based on OS
git maintenance start --scheduler=auto

# Purpose: Add another repository to maintenance list without altering existing scheduler
# Conditions: Execute in repository to be added; working directory can be clean or unclean
# Result: Registers current repository and completes same repository configuration as start, but doesn't create or start scheduler
git maintenance register
# Example 1: Scheduler already started by other repositories, add adjacent project-b to same maintenance list
cd ../project-b
git maintenance register

# Purpose: View registered repositories
# Result: Outputs all maintenance.repo values in current user's global config
git config --global --get-all maintenance.repo

# Purpose: Stop scheduled maintenance only for current repository
# Conditions: Current repository already registered; working directory can be clean or unclean
# Result: Removes current repository from maintenance list, other repositories and scheduler remain unchanged; maintenance.auto=false is still retained
git maintenance unregister
# Optional: Restore default behavior of regular Git commands triggering auto-maintenance as needed
git config --unset maintenance.auto

# Purpose: Pause scheduled maintenance for all registered repositories
# Conditions: Working directory can be clean or unclean
# Result: Stops and removes shared user-level scheduler, but retains maintenance list; executing start later can continue processing these repositories
git maintenance stop

# Purpose: Manually run specified tasks for explicit issues
# Conditions: Execution working directory can be clean or unclean; each <task> must be a supported task name
# Result: Only executes specified tasks in order of appearance, doesn't run other tasks
git maintenance run --task=<task> [--task=<task>...]
# Example 1: After importing massive commits, immediately update commit-graph
git maintenance run --task=commit-graph
# Example 2: Repository accumulated many loose objects and small pack files, execute incremental repack
git maintenance run --task=loose-objects --task=incremental-repack
# Example 3: When a full tidy is needed, run gc alone; don't put loose-objects in the same maintenance run
git maintenance run --task=gc

# Purpose: Only run task when repository reaches corresponding maintenance threshold
# Conditions: Execution working directory can be clean or unclean
# Result: Executes maintenance when threshold reached, otherwise doesn't alter repository data
git maintenance run --auto

git status --short --branch

git push origin feature/example

git pull

# If pull is using rebase
git rebase --abort

# If pull is using merge
git merge --abort

git fetch origin

# View the complete graph after the histories diverged
git log --graph --oneline --decorate --boundary \
  feature/example...origin/feature/example

# View only commits that exist on the remote but not locally
git log --oneline \
  feature/example..origin/feature/example

# Check whether those remote commits have patch-equivalent local versions
git cherry -v \
  feature/example origin/feature/example

# Purpose: Replace the old remote history with the rebased local history
# Conditions: You have fetched and confirmed that the remote contains only the pre-rebase commits; the branch may be rewritten
# Result: If the protective checks pass, updates origin/feature/example to the local feature/example
git push \
  --force-with-lease \
  --force-if-includes \
  origin feature/example

git fetch origin
git status --short --branch

# Print and manually verify the remote tip; in this example, it should be the old pre-rebase commit D
git rev-parse origin/feature/example

# Substitute the full commit ID from the previous command for <expected-remote-tip>
git push \
  --force-with-lease=refs/heads/feature/example:<expected-remote-tip> \
  origin feature/example:feature/example

# Conditions: The working tree has no uncommitted changes that would interfere with the merge
git merge origin/feature/example
git push origin feature/example

git cherry-pick <remote-new-commit>...

git switch -c feature/example-rebased
git push --set-upstream origin feature/example-rebased