@@ -124,3 +124,73 @@ what a commit is about.
124124
125125When you create a pull request, please
126126[ make your PR editable] ( https://github.com/blog/2247-improving-collaboration-with-forks ) .
127+
128+ ## Rebasing
129+
130+ If other PRs have been merged during the time between your initial PR creation
131+ and final approval, it may be required that you rebase your changes against the
132+ latest ` main ` branch.
133+
134+ There are potential pitfalls here if you follow the suggestions from ` git ` ,
135+ which could leave your branch in an unrecoverable mess,
136+ and you having to start over with a new branch and new PR.
137+
138+ The procedure below is tried and tested, and will help you avoid frustration.
139+
140+ To rebase a feature branch to the latest ` main ` :
141+
142+ 1 . Make sure that your local copy of the repository has the most up-to-date
143+ revisions of ` main ` (this is important, otherwise you may end up rebasing to
144+ an older base point):
145+ ``` bash
146+ git switch main
147+ git pull
148+ ```
149+ 1 . Switch to the (feature) branch to be rebased and make sure your copy is up to
150+ date:
151+ ``` bash
152+ git switch feature/something-cool
153+ git pull
154+ ```
155+ 1 . Consider taking a copy of the folder tree at this stage; this may help when
156+ resolving conflicts in the next step.
157+ 1 . Begin the rebasing process
158+ ``` bash
159+ git rebase main
160+ ```
161+ 1 . Resolve the conflicts in the reported files. (This will typically require
162+ reversing the order of the new entries in ` CHANGELOG.md ` .) You may use a
163+ folder ` diff ` against the copy taken at step 3 to assist, but bear in mind
164+ that at this stage ` git ` is partway through rebasing, so some files will have
165+ been merged and include the latest changes from ` main ` , whilst others might
166+ not. In any case, you should ignore changes to files not reported as having
167+ conflicts.
168+
169+ If there were no conflicts, skip this and the next step.
170+ 1 . Mark the conflicting files as resolved and continue the rebase
171+ ``` bash
172+ git add .
173+ git rebase --continue
174+ ```
175+ (You can alternatively use more specific wildcards or specify individual
176+ files with a full relative path.)
177+
178+ If there were no conflicts reported in the previous step, skip this step.
179+
180+ If there are more conflicts to resolve, repeat the previous step then this
181+ step again.
182+ 1 . Force-push the rebased (feature) branch to the remote repository
183+ ``` bash
184+ git push --force
185+ ```
186+ The ` --force ` option is important. Without it, you'll get an error with a
187+ hint suggesting a ` git pull ` is required:
188+ ```
189+ hint: Updates were rejected because the tip of your current branch is behind
190+ hint: its remote counterpart. Integrate the remote changes (e.g.
191+ hint: 'git pull ...') before pushing again.
192+ hint: See the 'Note about fast-forwards' in 'git push --help' for details.
193+ ```
194+ *** DO NOT*** follow the hint and execute ` git pull ` . This will result in the
195+ set of all commits on the feature branch being duplicated, and the "patching
196+ base" not being moved at all.
0 commit comments