This extension is not distributed with Mercurial.
Author: Bill Barry (BillBarry)
Mailing list: http://groups.google.com/group/hgattic
This module deals with a set of patches in the folder .hg/attic. At any time you can shelve your current working copy changes there or unshelve a patch from the folder.
Enable the extension by adding following lines to your configuration file (hgrc):
The extension adds a couple of commands, all starting with attic- so that they are grouped together in hg help, but all have shorter aliases:
Shelve will take the current changes to the working copy and create a patch in the attic:
hg shelve [name]
You need to supply a name for the patch when you first shelve it, but you can forget it if you are already working on a patch as, in that case, changes are added to the current patch.
This command comes with a lot of options, some are:
-m or --message
Use <text> as the commit message
-e or --edit
Bring up an editor to supply the commit message
-r or --refresh
Refresh the current patch without stowing it away
-i or --interactive
Use the 'record' extension to interactively select hunks for a shelf
as well as some for setting the user and the date. See the command help for more details.
Unshelve is the mirrored partner to shelve
hg unshelve [name]
(if any HUNK gets rejected because, for example, somebody else made changes to your files, you can consider using mpatch http://oss.oracle.com/~mason/mpatch/ to handle rejected files)
You need to supply a name if it isn't the same as the last patch you were working on. Ex:
... do some work hg shelve patch1 ... fix a bug hg ci -m "fixed bug" hg unshelve ... name is not needed here because it is assumed to be patch1
... do some work hg shelve patch1 ... work on something else hg shelve patch2 ... switch back to patch1 hg unshelve patch1 ... name is needed here because it is assumed to be patch2
The attic command displays the list of patches in the attic:
There are some options to change what it displays:
-c or --current
Show information about the current shelf being worked on
-d or --header
Show information about a given patch by name
Comparison with similar functionality
Attic is much like several other extensions, but still is different enough that you have a reason to choose one above the other.
Attic and mq are alike in that: 1. They both deal with patches and you can use patches from one wherever you can use patches from the other. 2. Both are designed to enable sharing patches.
Yet, these two extensions are very different. Mq is designed to work with a series of patches and attic is designed to work with a set of patches. If for example you have 3 patches that have nothing to do with each other in your series file in mq:
feature1 feature2 feature3
and you find that you are working on feature1 and suddenly realize there is a bug in feature2, you would:
hg qpush ... working on feature1 and realize bug hg qrefresh hg qpop ... reorder feature2 and feature1 (put feature2 first) hg qpush ... fix feature2 hg qrefresh hg qpop ... reorder feature2 and feature1 (put feature1 first) hg qpush ... continue working on feature1
whereas with attic:
hg unshelve feature1 ... working on feature1 and realize bug hg shelve hg unshelve feature2 ... fix feature2 hg shelve hg unshelve feature1 ... go back to feature1
While this process is workable in mq with only 3 patches, it grows unwieldly as your patch count increases.
In addition to providing different usecases to mq, attic works well alongside mq, for example: splitting a patch in mq (one way of many):
hg qgoto patchtosplit hg qpop ... move patchtosplit from .hg\patches to .hg\attic and remove it from series hg unshelve patchtosplit hg shelve -f --interactive patch1 hg shelve --interactive patch2 hg shelve therest hg unshelve --delete patchtosplit hg up -C qtip hg qimport .hg\attic\patch1 hg qimport .hg\attic\patch2 hg qimport .hg\attic\therest
working on feature1 and realize a fix for feature3, but you aren't ready to switch to it yet:
hg qpush ... work on feature1, realize fix for feature3 hg qrefresh ... make fix for feature3 hg shelve feature3-fix ... continue on feature1, eventually doing hg qrefresh hg qgoto feature3 hg unshelve --delete feature3-fix ... now test the changes and qrefresh
see also MqExtension
Though I (BillBarry) do not know enough about pbranch yet to provide an in depth discussion on it, I do know enough to say that pbranch can do just about everything that attic can do (perhaps interactive shelving is the only thing attic can do that pbranch cannot) and can also be used to provide long term support for patches (attic is designed for mostly quick and dirty stuff). Pbranch is more powerful than attic in multiple ways (one quick example: pbranch can deal with a full patch graph whereas attic only deals with one patch at a time). However, with the power of pbranch comes the complexity of pbranch.
see also PatchBranchExtension
Shelve (the interactive shelving extension) is almost entirely a subset of attic. In fact attic's hg shelve --interactive is calling 3 methods directly pulled from the hgshelve extension source code.
see also ShelveExtension
temporarily shelving something away to fix something else:
... working on something, bug comes in hg shelve mywork ... make fix hg ci -m "fixed bug" hg unshelve ... continue
... put bigpatch into .hg/attic hg unshelve bigpatch hg shelve -f --interactive patch1 hg shelve --interactive patch2 hg shelve finalpatch
all devs have attic under version control and 1 dev can pull from them: dev1 finishes feature: hg shelve -m "the message I want for the commit" -u featurea cd .hg/attic hg addrem hg ci -m "featurea ready" hg push (or whatever to make the patch public, example with shared repo assumed) dev2 finishes feature: hg shelve -m "the message I want for the commit" -u featureb cd .hg/attic hg addrem hg ci -m "featureb ready" hg push picker: cd .hg/attic hg pull cd ../.. hg unshelve featurea ... checks, it is ok hg ci (or move to mq, etc) hg unshelve featureb ... not ok hg shelve cd .hg/attic hg rm featurea hg ci -m "brought featurea into mainline" hg push
... patch1, patch2 and patch3 in attic hg unshelve --delete patch1 hg unshelve --delete -f patch2 hg unshelve --delete -f patch3 hg shelve foldedpatch
considering multiple implementations:
... do implementation 1 hg shelve impl1 ... do implementation 2 hg shelve impl2 ... do implementation 3 hg shelve impl3 ... converse with people about which patch is best hg unshelve impl2 hg ci -m "impl2 was best" cd .hg/attic rm impl1 rm impl3
Restrictions on patches
Don't create a patch with a name that starts with a period. It will not be shown with the attic-display command (and it could conflict with special files in the attic). Any special file in the attic is expected to start with a period (this is reserved for future usage as well).
Versioning the attic directory
You can put the attic under revision control, just ignore files that start with a period. This is particularly useful for sharing patches with a group of people.
Currently there are two special files:
contains the name of the current applied patch
contains the name of the assumed default patch