Using the Changes Browser

Index

Introduction; ChangeSet vs. ChangeFile
Change List Menu Functions
Main Menu Functions
The New ChangeSetBrowser
Recovering after a Crash
Keeping the Change File Small
Writing to Another Change File
Caution
Notice

Introduction; ChangeSet vs. ChangeFile

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' (*). Notice that the file used be called 'changes' in older ST/X versions and that its name can be changed in the settings dialog.

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 change set 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 chunk 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 change browser's 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 method's 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 method's 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 change browser; the change file (resp. changeSet) remains unmodified, unless you execute the "Writeback Change File" menu function.

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" operation (see below).

A change browser can be started either from the Launcher (it is found both in its toolbar and the "Tools" submenu), or by evaluating (in a workspace):

    ChangesBrowser open

The use of the changes browser is not limited to the 'st.chg' file; any file which contains expressiones in changefile format can be manipulated (technically, any Smalltalk source file has this format).
For example, a browser on a backup changeFile 'st.bak' file is opened with:

    ChangesBrowser openOn:'st.bak'

and, because Smalltalk's 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 people's changes into your current environment can also be done this way - by opening a changeBrowser on the other person's changeFile and applying changes as required.
Since this is a common task, the FileBrowser provides a menu-item for opening a change browser on the selected file in its tools menu.

A change set browser on the current (in-memory) change set can be opened by:

    ChangeSetBrowser openOn:(ChangeSet current)

or via the Launcher's "Classes" - "Recent changes" menu item.

Change List Menu Functions

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 or CTRL-s) 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 method's 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 file's 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 file's 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 file's 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.
Also be careful, with new changes which might have been done to the system in a class browser or the debugger, WHILE a changesbrowser has been open. When doing a writeback-changes, these new changes might be lost.
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.

Main Menu Functions

The main menu contains the same items as the popup-menu of the change list, plus a few additional menu entries:

File Menu Functions

Cleanup
Removes all changes for methods which are up-to-date (i.e. the last change is equal to the current in-image version, and the in-image version is not in the current change-set. In other words: the last version is the current compiled version.)

Change Menu Functions

--- to be documented ---

Search Menu Functions

--- to be documented ---

Browse Menu Functions

--- to be documented ---

Settings Menu Functions

--- to be documented ---

The New ChangeSetBrowser

The new ChangeSetBrowser2 adds multiple browser like view modes and icons which indicate the change's effect when applied.

Recovering after a Crash

After a crash of Smalltalk/X (or the machine), you should use a changes browser 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 window system or machine), you can simply execute the ``Apply Changes to End'' function.

Keeping the Change File Small

Since the change file grows over time (while programming), and having a big change file slows down the changes browser startup, old changes should be removed from time to time (say: "every month or so").
To do this, file out your classes completely or (better!) check them into a source repository and then remove all changes for that class, using the "Delete all for Class" menu function.

Also a regular compress (which removes all old changes for a method, just leaving the newest one) helps to keep the change file smaller.

Writing to Another Change File

The Launcher's ``Settings - Source & Debugger''-menu item opens a dialog for changging the name of the change file.
Change this if either two or more people are working in the same directory (to avoid one user to overwriting the other's change file) or to separate changes on a per project or per image basis (the name of the change file is saved with the image, so you only have to change this setting once per image).

Caution

The current implementation of the changes browser does NOT automatically update its view when new changes are made. Therefore, be careful when a changes browser is left open, while changes are made in another browser, and you execute the Writeback Changes function afterwards. Those new changes made in the meanwhile will then NOT be stored in the newly written changes file.

The changes browser 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.

To prevent confusion, do not leave a change browser open after repair work and continue working in a browser.

Notice

The functionality provided by the current changes browser 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'.
	]

Use this in code generators or test cases, when classes or methods are to be created by the program "on-the-fly". The above code 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. 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 Launcher's ``Settings'' - ``Source & Debugger'' dialog.