Sometimes a contributor sends a file of proposed changes instead of pushing a branch. A patch makes that exchange possible, but not every patch carries the same information. A plain diff describes file edits. A format-patch series additionally represents commits with messages and author metadata. Choosing the right receiving command prevents confusion about whether you have merely changed files or actually created commits. Use a clean disposable repository for this guide and run the complete Bash examples in Git Bash on Windows or a Bash terminal on another system.
Choose a representation for the review
git diff normally compares the working tree with the index. With --cached it compares staged changes with the current commit. Both commands can write a patch file using shell redirection. Before exporting, identify which comparison contains the intended work: an unstaged edit will not appear in a cached diff, and a staged edit will not appear in the default diff. Untracked files are another important boundary; they are not included merely because they are visible in the directory.
A patch is a proposed change relative to a base. It does not contain a complete project and is not a backup of every referenced file. Tell the recipient which revision to start from, which command produced it and whether it includes binary changes. For raw binary diffs, git diff --binary can include applicable binary data; a normal text-oriented diff may only report that binary files differ. Avoid promising that a small text patch contains every asset needed to build the project.
Inspect before changing files
git apply --stat summarizes a raw patch, while --check tests whether it can be applied without performing the application. Review the actual patch contents as well: successful application says the edits fit, not that they are correct or appropriate. Run checks from the expected repository location and inspect git status so unrelated work does not get mixed into the result. When the base differs, context lines may fail or match differently than you anticipated.
A normal git apply changes working-tree files without creating a commit. With --index, it updates the index too and requires the relevant index and working-tree versions to agree. That stricter mode is useful when you want the exact proposed changes staged for review. Run the matching --check mode first, then apply, inspect the diff and test the result. Do not reach immediately for options that ignore context or whitespace errors; first understand why the recipient's starting state differs.
Transfer a commit series with format-patch
git format-patch writes mailbox-style patches for commits selected by a revision range. Unlike a plain diff, each message contains author information and a commit message. git am imports those messages as new commits and uses your local committer identity. The resulting identifiers may differ because their parent or committer metadata differs. Treat the exchange as a transfer of proposed commits, not a promise that every original object identifier will survive unchanged.
Choose the range carefully. A two-dot range such as base..topic selects commits reachable from topic but not from base; it is not simply a count of files changed. Review the exported series in order and include a cover explanation when the change needs context. A series format helps reviewers understand incremental intent, but it does not remove the need for a known base, prerequisite changes and tests. Avoid exporting unrelated local commits merely because they happen to precede the intended work on a branch.
Handle failures as an explicit operation
An ordinary git apply failure leaves you investigating file application rather than a commit-series workflow. git am, on the other hand, can stop in the middle of a series. Inspect its state and the failing patch, resolve the intended files, stage the resolution and use git am --continue. If you decide the entire import should be abandoned, git am --abort restores the pre-operation state. Save unrelated work before starting instead of treating abort as a backup for arbitrary edits.
A three-way application can use recorded blob identities when the necessary base objects are available. It can help with drift, but it may still create conflicts and cannot reconstruct missing history magically. Review any resolution as a fresh edit; do not accept conflict markers or blindly select one side. When communicating with the sender, state the expected base and the failing patch number. That gives them a reproducible problem rather than an unexplained report that the patch did not work.
Sources and prerequisites
Review history, file management and cherry-pick first. The official diff, apply, format-patch and am references describe the different comparison and import modes.
Git Patches with diff, apply, format-patch and am Summary
- Select the correct comparison before exporting a raw diff.
- Use matching --check and application flags, then review the result.
- format-patch and am transfer a commit series; apply does not create commits.
Git Patches with diff, apply, format-patch and am Examples
Each example shows the code, the output it produces and what each part does.
Check and apply a raw diff to a matching clone
This local lab creates a sender, a receiver and one patch. The receiver starts from the sender's initial commit. No remote server is needed. The application uses --index so that the final cached diff shows the proposed change ready for review.
The summary reports one inserted line and one deleted line. The receiver has a staged edit and no new commit from git apply. The sender's edit remains unstaged because creating a patch does not commit or revert it. Review both repositories independently when following the state transitions.
mkdir patch-lab
cd patch-lab
git init -b main sender
git -C sender config user.name Learner
git -C sender config user.email learner@example.test
printf 'blue\n' > sender/color.txt
git -C sender add color.txt
git -C sender commit -m 'Initial color'
git clone sender receiver
printf 'green\n' > sender/color.txt
git -C sender diff > color.patch
git -C receiver apply --check --index ../color.patch
git -C receiver apply --index ../color.patch
git -C receiver diff --cached --numstat
cat receiver/color.txt1 1 color.txt
greenCommon Git Patches with diff, apply, format-patch and am Mistakes
Applying a patch from an unknown starting state
A successful --check should be performed against the state you will actually modify, using the same important flags as application. If files change afterward, repeat the check. Keep the base revision and unrelated edits explicit so the review does not silently combine separate work.
Git Patches with diff, apply, format-patch and am in Real Projects
Export a commit and apply it with git am
Continue in patch-lab. Reset the receiver's lab edit, commit the sender's proposed change and export that one commit. Import it with git am and inspect the resulting subject and file. Reset is safe here only because the receiver contains the disposable edit from the previous example.
git -C receiver reset --hard HEAD
git -C sender add color.txt
git -C sender commit -m 'Use green'
git -C sender format-patch -1 HEAD --stdout > series.patch
git -C receiver config user.name Receiver
git -C receiver config user.email receiver@example.test
git -C receiver am ../series.patch
git -C receiver log -1 --format='%s'
cat receiver/color.txtUse green
greenInitialization, reset and import progress messages also appear. The final subject demonstrates that git am created a commit using the transmitted message. Inspect %an and %cn to see the sender as author and Receiver as committer. Compare this with the first example, where a raw patch only changed the working tree and index.
Git Patches with diff, apply, format-patch and am FAQ
Why did my untracked file disappear from the exported diff?
A default git diff compares tracked working-tree content with the index. A new untracked file is outside that comparison. If the file belongs in the proposed change, stage it and export the appropriate cached diff, or commit the complete change and use format-patch. Check git status and review the exported file list before sending. Do not infer patch completeness from the number of files visible in your editor.
Does git apply preserve the original commit message?
A raw diff does not provide a commit-import operation. git apply modifies files and optionally the index; it does not create a commit with an author or message. You can review and commit the resulting edit yourself. If the exchange needs commit messages and author metadata for a series, use git format-patch on the sender and git am on the receiver, then inspect the imported history.
When should I use git am --abort?
Use it when an active mailbox-patch import should be abandoned and restored to its pre-import state. First inspect status so you understand the operation you are aborting. If you intend to keep a resolved import, stage the resolution and continue instead. Start from a clean repository or separately saved work; aborting an import is not a general way to recover every unrelated change made during the session.
Is a patch file a complete offline repository backup?
No. It represents selected changes and may depend on base files or objects that the recipient already has. A format-patch series adds commit-oriented metadata but still does not replace a complete repository transfer. Use a Git bundle when you need an offline package of selected Git history, and preserve external asset stores separately when applicable. Choose the artifact according to whether you are reviewing edits, importing commits or recovering history.
Git Patches with diff, apply, format-patch and am Exercises
Answer each one and check it instantly. If you get stuck, open the hint before the answer.
After the first patch-lab example, what did git apply --index create in receiver?
Git Patches with diff, apply, format-patch and am Quiz
2 questions to check what you learned.
Which export is intended for importing author metadata and commit messages with git am?
- git status --short
- git format-patch
- git diff --stat
What does git apply --check establish?
- The proposed program passes its test suite
- The sender's identity has been cryptographically verified
- The selected application mode can apply the patch to the current state