Overview#

Aftersetting up a development environment, the typicalworkflow is:

1. Fetch all changes fromupstream/main:

   gitfetchupstream

2. Start a newfeature branch fromupstream/main:

   gitcheckout-bmy-featureupstream/main

3. When you're done editing, e.g.,lib/matplotlib/collections.py, record your changes in Git:

   gitaddlib/matplotlib/collections.pygitcommit-m'a commit message'

4. Push the changes to your GitHub fork:

   gitpush-uoriginmy-feature

Explore your repository#

To see a graphical representation of the repository branches andcommits:

gitk--all

To see a linear list of commits for this branch:

gitlog

Recover from mistakes#

Sometimes, you mess up merges or rebases. Luckily, in git it isrelatively straightforward to recover from such mistakes.

If you mess up during a rebase:

gitrebase--abort

If you notice you messed up after the rebase:

# reset branch back to the saved pointgitreset--hardtmp

If you forgot to make a backup branch:

# look at the reflog of the branchgitreflogshowcool-feature8630830cool-feature@{0}:commit:BUG:io:closefilehandlesimmediately278dd2acool-feature@{1}:rebasefinished:refs/heads/my-feature-branchonto11ee694744f2552d26aa21acool-feature@{2}:commit:BUG:lib:makeseek_gzip_factorynotleakgzipobj...# reset the branch to where it was before the botched rebasegitreset--hardcool-feature@{2}

Rewrite commit history#

Is there an embarrassing typo in a commit you made? Or perhaps youmade several false starts you don't want posterity to see.

This can be done viainteractive rebasing.

Suppose that the commit history looks like this:

gitlog--onelineeadc391Fixsomeremainingbugsa815645Modifyitsothatitworks2dec1acFixafewbugs+disable13d7934Firstimplementation6ad92e5*maskedisnowaninstanceofanewobject,MaskedConstant29001edAddpre-nepforacopuleofstructured_array_extensions....

and6ad92e5 is the last commit in thecool-feature branch. Suppose wewant to make the following changes:

• Rewrite the commit message for13d7934 to something more sensible.

• Combine the commits2dec1ac,a815645,eadc391 into a single one.

We do as follows:

# make a backup of the current stategitbranchtmpHEAD# interactive rebasegitrebase-i6ad92e5

This will open an editor with the following text in it:

pick13d7934Firstimplementationpick2dec1acFixafewbugs+disablepicka815645Modifyitsothatitworkspickeadc391Fixsomeremainingbugs# Rebase 6ad92e5..eadc391 onto 6ad92e5## Commands:#  p, pick = use commit#  r, reword = use commit, but edit the commit message#  e, edit = use commit, but stop for amending#  s, squash = use commit, but meld into previous commit#  f, fixup = like "squash", but discard this commit's log message## If you remove a line here THAT COMMIT WILL BE LOST.# However, if you remove everything, the rebase will be aborted.#

To achieve what we want, we will make the following changes to it:

r13d7934Firstimplementationpick2dec1acFixafewbugs+disablefa815645Modifyitsothatitworksfeadc391Fixsomeremainingbugs

This means that (i) we want to edit the commit message for13d7934, and (ii) collapse the last three commits into one. Now wesave and quit the editor.

Git will then immediately bring up an editor for editing the commitmessage. After revising it, we get the output:

[detachedHEAD721fc64]FOO:Firstimplementation2fileschanged,199insertions(+),66deletions(-)[detachedHEAD0f22701]Fixafewbugs+disable1fileschanged,79insertions(+),61deletions(-)Successfullyrebasedandupdatedrefs/heads/my-feature-branch.

and now, the history looks like this:

0f22701Fixafewbugs+disable721fc64ENH:Sophisticatedfeature6ad92e5*maskedisnowaninstanceofanewobject,MaskedConstant

If it went wrong, recovery is again possible as explainedabove.

If you have not yet pushed this branch to github, you can carry on as normal,however if youhave already pushed this commit seePush with force for howto replace your already published commits with the new ones.

Rebase ontoupstream/main#

Let's say you thought of some work you'd like to do. YouUpdate the main branch andMake a new feature branch calledcool-feature. At this stage,main is at some commit, let's call it E.Now you make some new commits on yourcool-feature branch, let's call themA, B, C. Maybe your changes take a while, or you come back to them after awhile. In the meantime,main has progressed from commit E to commit (say) G:

      A---B---C cool-feature     /D---E---F---G main

At this stage you consider mergingmain into your feature branch, and youremember that this page sternly advises you not to do that, because thehistory will get messy. Most of the time, you can just ask for a review withoutworrying about whethermain has got a little ahead; however sometimes, the changes inmain might affect your changes, and you need to harmonize them. In thissituation you may prefer to do a rebase.

rebase takes your changes (A, B, C) and replays them as if they had beenmade to the current state ofmain. In other words, in this case, it takesthe changes represented by A, B, C and replays them on top of G. After therebase, your history will look like this:

              A'--B'--C' cool-feature             /D---E---F---G main

Seerebase without tears for more detail.

To do a rebase onupstream/main:

# Fetch changes from upstream/maingitfetchupstream# go to the feature branchgitcheckoutcool-feature# make a backup in case you mess upgitbranchtmpcool-feature# rebase cool-feature onto maingitrebase--ontoupstream/mainupstream/maincool-feature

In this situation, where you are already on branchcool-feature, the lastcommand can be written more succinctly as:

gitrebaseupstream/main

When all looks good, you can delete your backup branch:

gitbranch-Dtmp

If it doesn't look good you may need to have a look atRecover from mistakes.

If you have made changes to files that have also changed inmain, this maygenerate merge conflicts that you need to resolve - see thegit rebase manpage for some instructions at the end of the "Description" section. There issome related help on merging in the git user manual - seeresolving a merge.

If you have not yet pushed this branch to github, you can carry on as normal,however if youhave already pushed this commit seePush with force for howto replace your already published commits with the new ones.

Push with force#

If you have in some way re-written already pushed history (e.g. viaRewrite commit history orRebase onto upstream/main) leaving you witha git history that looks something like

  A'--E cool-feature /D---A---B---C origin/cool-feature

where you have pushed the commitsA,B,C to your fork on GitHub (under theremote nameorigin) but now have the commitsA' andE on your localbranchcool-feature. If you try to push the new commits to GitHub, it willfail and show an error that looks like

$gitpushPushingtogithub.com:origin/matplotlib.gitTogithub.com:origin/matplotlib.git![rejected]cool_feature->cool_feature(non-fast-forward)error:failedtopushsomerefsto'github.com:origin/matplotlib.git'hint:Updateswererejectedbecausethetipofyourcurrentbranchisbehindhint:itsremotecounterpart.Integratetheremotechanges(e.g.hint:'git pull ...')beforepushingagain.hint:Seethe'Note about fast-forwards'in'git push --help'fordetails.

If this push had succeeded, the commitsA,B, andC would nolonger be referenced by any branch and they would be discarded:

D---A'---E cool-feature, origin/cool-feature

By defaultgitpush helpfully tries to protect you from accidentallydiscarding commits by rejecting the push to the remote. When this happens,GitHub also adds the helpful suggestion to pull the remote changes and then trypushing again. In some cases, such as if you and a colleague are bothcommitting and pushing to the same branch, this is a correct course of action.

However, in the case of having intentionally re-written history, wewant todiscard the commits on the remote and replace them with the new-and-improvedversions from our local branch. In this case, what we want to do is

$gitpush--force-with-lease

which tells git you are aware of the risks and want to do the push anyway. Werecommend using--force-with-lease over the--force flag. The--force will do the push no matter what, whereas--force-with-leasewill only do the push if the remote branch is where the localgit clientthought it was.

Be judicious with force-pushing. It is effectively re-writing publishedhistory, and if anyone has fetched the old commits, it will have a different viewof history which can cause confusion.

Skip CI checks#

If you know only a subset of CI checks need to be run, you can skip unneeded CI checkson individual commits by including the following strings in the commit message:

[skipactions] and[skipci] only skip Github Actions CI workflows that aretriggered onon:push andon:pull_request events. For more information,seeSkipping workflow runs.