Ideas/RebaseStatus
This page documents the current status of Rebase. The design page has a general design discussion.
What is rebase?
Conceptually, rebase is a sophisticated version of the “diff and patch” approach that people are sometimes driven to when they need to make changes to patches with dependencies in a darcs repository. With rebase, patches can be held in a “suspended” state for a period of time. Crucially, rebase is built on the darcs patch handling code and it can use this to avoid any of the fuzziness associated with applying diffs to a changed tree - it keeps track of how the tree has changed. It also means that patches that can’t be expressed naturally as diffs (e.g. file move, token replace) do not lose information.
Where do I get it?
darcs get http://urchin.earth.li/darcs/ganesh/darcs-branches/rebase–20110110/
The feature is currently maintained on a branch, which is itself subject to frequent rebasing to test the feature out. Therefore you should do a fresh get if you want to update.
What’s the current status
Very much a preview. Lots of feature work still to do. The UI needs to be improved and polished.
Also, be aware that this branch tracks darcs HEAD, which is itself prone to instability and breakage.
What can I do with it?
Rebase is primarily intended for two scenarios, though it may well find other uses over time.
“Deep” amend-record, where the patch to be amended has dependencies.
Doing a merge without conflicts, by editing the conflicts out of the patches in one branch of the merge. This is important for long running branches where conflicts can get out of hand over time.
As with amend-record, changing a patch with rebase means that its identity changes. This also applies to all dependencies of the patch.
How do I use it?
To suspend a patch from the repository, use
darcs rebase suspend
If the patch has dependencies, these must be suspended too. The normal rules of interactive selection and dependencies apply here.
To restore a suspended patch, use
darcs rebase unsuspend
When a patch is unsuspended, it is given a new identity. This means that once a patch has been suspended, you are committed to changing its identity.
To pull patches from a remote repository, suspending any local patches that will then be in conflict, use
darcs rebase pull
There is an obvious asymmetry to this command in that we cannot choose to suspend the remote patches instead. This is mainly because suspending the local patches is easiest to implement.
Recipes
Deep amend-record
- darcs rebase suspend —patch ‘patchname’
[answer ‘y’ to all patches] or
- darcs rebase suspend
[answer ‘w’ to all patches until you get to the one you want, then ‘y’, then ‘d’]
- darcs rebase unsuspend
[select the first patch, which will be the one you want to amend-record]
- darcs amend-record
[edit the patch as required]
For each remaining suspended patch,
darcs rebase unsuspend
There may be conflicts caused by the amendment. In this case, resolve the conflicts and use darcs amend-record to update the newly unsuspended patch.
Merge from upstream
- darcs rebase pull upstream
- [select the patches to pull, then answer ‘y’ to each patch that is offered for suspending]
as with deep amend-record, iterate ‘darcs rebase unsuspend’ along with conflict resolution where necessary until done.
Notes
Currently any explicit dependencies will be dropped (and you will be warned) when unsuspending a patch.
The suspended patches are stored in a special patch in the repository. As the patch description warns you, do not operate on this patch directly or bad things will happen.
TODO
Handle explicit dependencies properly.
add ‘darcs amend-record —suspend’ or similar to simplify the deep amend-record workflow
allow force-reordering of dependent suspended patches
Lots more!
Contact
Please send feedback to darcs-users@darcs.net (you need to be subscribed) or to ganesh@earth.li
