[prev] [up] [next]

Using the Changes Browser

Index

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:

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). Pressing the Control (CTRL-) Key while right clicking brings up a search menu.

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.

[stx-logo]>
Copyright © 1995 Claus Gittinger Development & Consulting, all rights reserved
<P>
<ADDRESS>
<tt><<a href=cg@exept.de>


Doc $Revision: 1.36 $ $Date: 2016/11/04 00:19:00 $