Using the Changes Browser
Smalltalk/X keeps track of all your changes made to either
the class hierarchy or to individual methods both in memory, in the so called ChangeSet
and in a ChangeFile called 'st.chg'
.
The file used to be 'changes'
in older versions.
(*).
For each change, one record
is appended both to the ChangeSet and to the ChangeFile (**).
The "ChangeSet" is a collection kept in memory, and grows over time.
However, it is compressed, whenever a class is checked into the source repository (CVS, SVN, etc.).
It can also be manually cleared, via the SystemBrowser's special-cleanup-changeSet
function in its class menu,
or by opening a ChangeSetBrowser.
As the changeSet is kept in memory, it is lost in case of a crash (in contrast to the change file, which is persistent).
The change-file is never cleared automatically, and therefore is even available
for repair and undo in case of a crash, power failure or when ST/X is exited without
an image being written. It also grows, unless modified via the ChangesBrowser.
The file contains readable ascii text, called "chunks". A chunks is a single change as done by
the programmer in a special format (delimited by exclamation marks).
Do not manipulate the change file manually (for example in a text editor), unless you know exactly what you are doing.
A ChangeBrowser allows inspection and manipulation of the "Change-file"
(which is on your disk and contains individual change-chunks as text).
A ChangeSetBrowser allows inspection and manipulation of a "ChangeSet"
(which is an in-memory list of change-objects).
Both consist of 2 subviews; which are:
- change list view
- contents (and diff-) view
The change list view (top panel) displays a list of changes in chronological order.
If the "automatic compare" option has been enabled in the changeBrowsers settings,
change-entries are marked with one of the following characters in the first column:
- +
- The change adds a method. I.e. the changeFile contains code for a method
which is not present in your current running image.
- -
- The change removes a method. I.e. the changeFile contains an entry to
remove a method which is still present in your running image.
- =
- The change has no effect, as the methods code in the changeFile is the same as
the code of the one present in your image.
- ~
- The change has no effect semantically; this means that although the methods code
in the changeFile is different from the methods code in your image,
the statements and effect are the same. Typically, this means that the code has only been
reformatted, and/or comments have been changed.
- ?
- The effect of the change cannot be determined, as the affected class is not loaded/present
in your running image.
To see a change, select (i.e. click on) the corresponding line in the
changelist. The change will be displayed in the contents view.
A double click on a changeList-item brings up a class-browser on the current (in-image)
version of the corresponding method, if it exists.
Don't be afraid using the changesBrowser, the changes file (resp. changeSet) remains
unmodified unless you execute the "writeback change file"
function from the
menu.
The text shown in the contents view is readonly -
changes cannot be changed.
The accept function of the contents view has been redefined to
perform an apply change (see below).
A changeBrowser can be started either from the launcher
(it is found in the "Tools"
submenu),
or by evaluating the expression
(in a workspace):
ChangesBrowser open
Use of the changesBrowser is not limited to the 'changes'
file;
any file which contains expressiones in changefile-format can be manipulated.
For example, a browser on a backup changeFile 'changes.bak'
file is opened with:
ChangesBrowser openOn:'changes.bak'
and, because Smalltalks regular fileOut (i.e. source-file) format also consists
of chunks, it can be even opened on a classes source:
ChangesBrowser openOn:'../../libbasic/Object.st'
which is useful to import, compare or investigate other/public-domain smalltalk code.
In addition to reapplying or undoing previous changes to the system,
integration/merge of other peoples changes into your current
environment can also be done this way -
by opening a changeBrowser on the other persons changeFile
and applying changes as required.
Since this is a common task, the FileBrowser provides
a menu-item for opening a changeBrowser on the selected file in its tools menu.
A changeSetBrowser on the current changeSet can be opened by:
ChangeSetBrowser openOn:(ChangeSet current)
or via the launchers "Classes" - "Recent changes" menu item.
The top part of the changes browser is called changelist view and
offers the following functions in its popup menu:
(notice: new versions of the changeBrowser also provide these functions in the main window menu).
- Apply
apply the currently selected change(s) (i.e. redo it)
The accept key (usually CMD-a) in the codeview
performs this funtion too.
- Apply to End
apply all changes from the currently selected one up to the end.
- Apply for Class to End
apply all changes from the currently selected one up to the end
which affect the same class as the currently selected changes class.
- Apply All
apply all changes from the very first to the very last in the list
- Delete
delete the currently selected change(s)
from the list (the deletion becomes effective
when the change-list is written back to the
changes file - see below)
Pressing the Delete key in the changeList view has the same effect.
- Delete to End
delete all changes from the currently selected one up to the end.
- Delete for Class to End
delete all changes which affect the same classas the currently selected change, up to
the end.
- Delete all for Class
delete all changes (from the beginning to the end)
which affect the same class(es) as the currently selected changes class(es).
(useful after a class-fileOut or checkIn - but see below)
- Delete all for Class & its private Classes
delete all changes (from the beginning to the end)
which affect the same class(es) as the currently selected changes class(es),
or one of its/their private classes.
(useful after a class-fileOut or checkIn, because private classes are checked into
the owning classes container)
- Compress
compress the change list.
This function removes multiple changes for a method leaving the last one.
- Compress for class
compress the change list, but only changes which affect the class
of the currently selected change.
This function removes multiple changes for a method leaving the last one.
- Compare and Compress
compress the change list by removing all method changes which are
already applied - i.e. which have the same source as the currently
installed method.
- Compare with current Version
compare a methods code in a change with
the current and output a message on the
Transcript. If there are any differences,
open up a view showing differences.
- Browse Class
opens a browser on the class of the current change.
A doubleClick on an entry in the changeList performs the same.
- Make change a patch
append the change to the end of the
'patches'
file, making the change be
automatically applied on the next startup.
- FileOut & Delete all for Class
saves the class of the selected change (as in the system - NOT as in the
changefile) and removes all changes for that class from the changeList.
- CheckIn & Delete all for Class
checks the class of the selected change (as in the system - NOT as in the
changefile) into the sourceCode repository
and removes all changes for that class from the changeList.
- Save in...
append the current changes text to a file.
A DialogBox will ask you for the files name.
This function is useful to 'move' changes from
another change file into yours, or to create a filtered change file
to be delivered to others.
- Save to End in...
append all changes from the currently selected one to the
last change to a file.
A DialogBox will ask you for the files name.
This function is useful to 'move' changes from
another change file into yours, or to create a filtered change file
to be delivered to others.
- Save for Class to End in...
append all changes from the currently selected one to the
last change which affect the same class as the currently selected change
to a file.
A DialogBox will ask you for the files name.
- Save all for Class in...
append all changes from the very first one to the
last change which affect the same class as the currently selected change
to a file.
A DialogBox will ask you for the files name.
- Writeback changefile
writeback the change list (as currently shown in the changesBrowser)
to the changes file.
None of the above operations actually modify the changes file -
all operations are performed on an internal (in-memory) copy.
Any delete/compress operations
performed in the changesBrowser do
NOT affect the changes-file, UNLESS this writeback-operation is performed.
Be careful, to never writeBack a changeFile after deletions of changes
which you may need later and which cannot be recovered (i.e. you did not
fileOut the class).
The writeBack operation keeps a save copy of the previous changes-file contents
(as "changes.sav") which can be used in case of disaster. However, only the
last version is kept - older changefile versions are lost, unless you copied
that file before the writeBack.
- Update
reread the changes file
(useful as an undo or if new changes have been made in the meanwhile)
Pressing the Control (CTRL-) Key while right clicking brings up a search menu.
After a crash of Smalltalk/X (or the machine), you should use a changesBrowser to
reapply all changes made. Usually, you would look for the last
"snapshot"-entry in the change list and apply all changes after that
one up to the end.
If the crash was caused by one of those changes
(for example, you redefined a system method), the best approach is
to manually apply individual changes upto, but excluding the 'bad'-one..
If the crash was caused by a system breakDown or power failure
(or because you forgot to leave ST/X before shutting down the windowSystem),
you can execute the ``apply changes to end'' function.
Since the change file grows over time (while programming),
and having a big changefile slows down the ChangesBrowser startup,
old changes should be removed from time to time.
To do this, classes should be filed out completely and all changes for
that class be removed.
Also a regular compress (which removes all old changes for a
method, just leaving the newest one) helps to keep the change file
smaller.
The launchers ``settings-source & debugger''-menu item opens a dialog which
allows for changging the name of the changeFiles.
Change this if either two or more people are working in the same directory (to avoid one
user to overwrite the others change file) or to separate changes on a per project
or per image basis (the name of the changeFile is saved with the image).
The current implementation of the changesBrowser does NOT
automatically update its view when new changes are made.
Therefore, be careful when a changesBrowser was left open,
while changes were made in a browser, and you perform the
writeback changes function.
These changes made in the meanwhile will then NOT
be stored in the newly written changes file.
The changesBrowser will display ``(outdated)'' in the window title,
whenever it detects that new changes have been written to the changefile,
and the displayed list is not in-sync with it.
If in doubt, perform the update function.
The functionality provided by the current changesBrowser is probably far
from being complete and more functions are required - especially
when working in a group on a big project.
If you add any enhancements or extra features, please return them to eXept
for inclusion into the next release(s).
Notes:
- (*)
-
If your program wants to create/modify a class or method without
the change being recorded, execute the modifying code inside
a
withoutUpdatingChangesDo:
block.
I.e. to create a new class which is not recorded, write:
Class
withoutUpdatingChangesDo:[
Object
subclass:#Foo
instanceVariableNames:'i1 i2'
classVariableNames:''
poolDictionaries:''
category:'temporary - not recorded in the changeSet/File'.
]
Notice that this is thread-safe; i.e. other processes (especially browsers)
would still record their changes
- (**)
-
By default, the system only adds changed class and method definitions
to the changefile. Expressions evaluated by the
"doit"
function
are not appened. (to keep the changefile from growing too fast).
If you want doits to be remembered too, execute:
Smalltalk logDoits:true
in a workspace
or add it to your startup file
('smalltalk.rc'
or 'private.rc'
),
or use the launchers ``settings-source & debugger'' dialog.
cg@exept.de>
Doc $Revision: 1.28 $ $Date: 2012/03/06 09:24:55 $