1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
|
Shelve
======
.. module:: shelve.dialog
:synopsis: Dialog used to perform shelve/unshelve operations
.. warning::
The win32text extension can cause trouble with hunk selection. This
has been resolved in Mercurial 1.3 and TortoiseHg 0.8, but requires
proper configuration. See
`issue #82 <http://bitbucket.org/tortoisehg/stable/issue/82/>`_.
The purpose of this dialog is to allow the user to *shelve* selected changes
from the working directory, store them in a special patch file within the
repository, and then *unshelve* them back at a later time.
.. figure:: figures/shelve.png
:alt: Shelve dialog
Shelve dialog
Walking across the toolbar buttons:
:guilabel:`Shelve`
Shelve selected diffs in checked files.
:guilabel:`Unshelve`
Replace the shelved changes back into the working directory.
:guilabel:`Diff`
Visual diff checked files
:guilabel:`Revert`
Revert checked files to last revisioned state. If merging, it
allows you to select the revert parent.
:guilabel:`Add`
Add checked files that were in unknown '?' or ignored 'I' state.
:guilabel:`Move`
Move checked files to specified target directory in versioned
manner.
:guilabel:`Remove`
Delete checked unversioned files and/or remove (mark as deleted) any
versioned files.
:guilabel:`Forget`
Forget checked versioned files
:guilabel:`Refresh`
Reload the state of the working directory. It tries to retain
check and selection state across refresh.
The file list has four columns:
1) A checkbox that indicates whether the file is selected for an
operation. The toolbar buttons only operate on checked files.
"Partially" selected files have a special check state. This
column header is checkable, it will toggle the file selection
states.
2) The :guilabel:`st` column holds the status of the file, defined
by Mercurial's status command, one of 'MARD?IC'.
3) The :guilabel:`ms` column holds the merge state of the file,
defined by Mercurial's resolve command, one of ' RU'.
4) The canonical path of the file (relative to the repository root)
Below the file list are checkboxes that toggle the display of the
various classes of files {modified, added, removed, deleted, unknown,
clean, ignored}. These check boxes will be disabled if the commit tool
was given a specific set of files and/or directories.
Tabs
----
The shelve tool diff pane has four tabs
1) Text Diff - shows diff of currently selected file
2) Hunk Selection - allows diff hunks of current file to be skipped
3) Shelf Preview - displays all selected changes. This previews the
changes that will be removed from the working directory and
stored in the shelf.
4) Shelf Contents - the current contents of the shelf.
Shelving Changes
----------------
Just like the commit tool, this dialog uses TortoiseHg's integrated hunk
selection code to allow the user to select the files and change hunks to
move to the shelf. When you press the shelve button, the selected
changes are removed from the working directory and placed in a patch
file. If the shelf already had changes in it, you will be asked whether
to replace those changes or to merge these new changes into it. When
the shelf has changes, the unshelve button will be active.
Unshelving Changes
------------------
When the unshelve button is pressed, the shelved changes are reapplied
to the working directory.
.. note::
The unshelved changes will appear as working directory modifications
when the shelve tool refreshes it's view of the repository.
How is this different from record/commit?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Shelved changes are physically removed from the working directory until
you unshelve them. This means you can build your project and run tests
on it while the shelved changes are gone. This is safer than selecting
changes at build time since you can test whether the change being
committed is valid.
Shelving changes is also useful for removing partially completed work to
make sure it doesn't interfere with the debugging of other changes you
are making.
Caveat: the shelved changes are stored in a patch that is based on the
current working directory contents. There's no guarantee that the patch
can be cleanly reapplied later if the shelved changes conflict with
changes made to your code after the shelving.
How is this different from MQ?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The shelf can be considered a single unnamed MQ patch that is never
converted into a changeset.
The shelve tool can be useful when maintaining a patch queue.
The shelf can take changes from one patch and re-apply them to another
patch (or an entirely new patch).
For example:
1) Push to a patch you would like to split up
2) Open the shelve tool, the top patch changes will be selectable
3) Unselect change hunks you want to leave in the patch, then press
:guilabel:`Shelve`
4) Refresh top patch using :command:`hg qrefresh`, or use commit tool
5) Push or pop to the patch you want to apply shelved patches
6) Open the shelve tool and press :guilabel:`Unshelve`
7) Refresh top patch (repeat step 4)
You cannot shelve added, removed, or renamed files, but MQ can handle
this just fine.
How is this different from attic?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The attic extension is a super-set of the shelve feature. In particular,
attic allows you to have several named *shelves* which can be saved and
restored independently.
Keyboard navigation
-------------------
:guilabel:`Ctrl-C`
in the diff panel will copy the currently highlighted (not selected,
but highlighted) diff hunks to the clipboard. These can be pasted
into a text buffer to generate any arbitrary patch based from the
changes in your working directory.
The code which copies the hunks to the clipboard is intelligent about
diff headers. The clipboard contents will always be a valid patch.
Configurables
-------------
* :menuselection:`TortoiseHg --> Bottom Diffs`
* :menuselection:`TortoiseHg --> Tab Width`
* :menuselection:`TortoiseHg --> Max Diff Size`
From command line
-----------------
The shelve tool can be started from command line::
hgtk shelve
aliases: unshelve
shelve/unshelve tool
use "hgtk -v help shelve" to show global options
To use TortoiseHg's shelve functionality from the Mercurial command
line, you must enable the extension with lines like these in your
Mercurial.ini file::
[extensions]
tortoisehg.util.hgshelve=
This adds commands named :command:`shelve` and :command:`unshelve` to hg.
.. vim: noet ts=4
|
