Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 38 ยท Tools and Image Workflow

Monticello, Iceberg and Git

Learn how Smalltalk code is versioned: Monticello packages and snapshots, Iceberg and Git in Pharo, Tonel files, commits, branches and merges. Real tools are read-only; a runnable diff stand-in is included.

An image is a binary snapshot of live objects, so you cannot put it under version control and expect useful diffs. Smalltalk teams version packages instead: named groups of classes and methods that can be exported, compared and merged. Two generations of tools do this. Monticello is the classic system used by Squeak and older Pharo. Iceberg is Pharo's modern integration with Git, so Smalltalk projects live in ordinary GitHub or GitLab repositories.

This lesson explains both ideas, the file format that makes Git practical, and the daily workflow. Neither tool runs on this site: commands and screens are read-only. A stand-in at the end implements a small package diff in JavaScript so you can see what "comparing a package" means.

What a package is

In the system browser, classes belong to packages, and methods can be grouped into extensions that belong to a different package than their class. A package therefore has three kinds of content (read-only):

SMALLTALK
"Package: Bank-Core"
Object subclass: #Account ...            "a class defined here"
Account >> deposit: amount ...           "a method defined here"
Integer >> asMoney ...                   "an EXTENSION: lives in Bank-Core, adds to Integer"

Monticello and Iceberg both track this set. When you load a package, the class definitions and methods are compiled into your image. When you save one, the current definitions are written out as a version.

Monticello

Monticello stores each version as a snapshot of the package plus ancestry information, and it keeps these in repositories: a directory, an HTTP server such as SmalltalkHub, or a local cache. The Monticello Browser lists working copies; a modified package shows an asterisk. Typical actions (read-only):

  • Changes compares the working copy with its last saved version and shows added, removed and modified methods.
  • Save writes a new .mcz version with a message.
  • Merge merges another version into the image, with a conflict dialog per method.
  • Load brings a version in.

A Monticello version is a compressed archive, not human-readable text, so it never played well with general tools. That is the problem Tonel solved.

Tonel: source files that Git can diff

Tonel writes each class to its own text file, with methods in readable form (read-only):

SMALLTALK
Class {
	#name : #Account,
	#superclass : #Object,
	#instVars : [ 'balance' ],
	#package : #'Bank-Core'
}

{ #category : #operations }
Account >> deposit: amount [
	balance := balance + amount
]

Because each class and method is plain text, Git can show line-by-line diffs, pull requests work normally and git blame points at the author of a method. A repository typically contains src/Bank-Core/Account.class.st, src/Bank-Core/package.st, plus a .project and .git files.

Iceberg: Git inside Pharo

Iceberg is the Pharo tool window for Git. You can clone a repository, load its packages, and then work as usual. The core loop (read-only) looks like this:

  1. Clone or create a repository in the Iceberg window; choose which packages to track.
  2. Edit code in the system browser. Iceberg marks changed packages.
  3. Review the diff in Iceberg's Commit tab: it shows changed classes and methods, not whole files.
  4. Commit with a message, then Push.
  5. Pull to get a teammate's work, resolving conflicts in a diff view.
  6. Branches: create and switch from the Iceberg window; the image reloads the differences.

Most developers also keep a command-line Git at hand because the files are ordinary text. A script can load the project into a fresh image:

SMALLTALK
Metacello new
    baseline: 'Bank';
    repository: 'github://example-user/bank:main/src';
    load.

That Metacello expression, explained in Metacello baselines and package loading, is how a CI server rebuilds the project from nothing.

A good routine

  • Commit small and often, one idea per commit, with a message that says why.
  • Keep the repository free of images: add *.image, *.changes and pharo-local/ to .gitignore.
  • Before you pull, commit or stash, then run the tests afterwards because a merge can compile but misbehave.
  • Never share an image; share a baseline and a loading script.
flowchart LR
  IMG["working image"] -->|"edit + test"| IMG
  IMG -->|"commit (Tonel files)"| LOC["local Git repo"]
  LOC -->|"push"| REM["GitHub / GitLab"]
  REM -->|"pull / CI loads baseline"| IMG

The image is private; the Git repository is the shared truth.

Stand-in: comparing two package versions

A "Changes" view is a comparison of two method tables. The following JavaScript does that for two small packages: it reports added, removed and modified methods, just like the Monticello and Iceberg diff lists.

JS Stand-in: a package diff

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Real tools compare syntax trees rather than raw strings, so renaming a temporary variable still shows as a modification but whitespace-only changes can be ignored.

JS Stand-in: merging two edits to different methods

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The second call changes the same method on both sides, which is a conflict that a person must resolve.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why is a Smalltalk image not stored in Git?

    Version packages as text (Tonel) and rebuild images from them.
  2. 2. What does Tonel provide?

    Each class is a text file with readable methods, so diffs and blame work.
  3. 3. What is an extension method?

    A package can add methods to classes defined elsewhere, such as Integer>>asMoney in Bank-Core.
  4. 4. What should a .gitignore for a Pharo project exclude?

    Those files are local build output; the source of truth is the Tonel files.

Summary

  • Version packages, not images.
  • Monticello stores package snapshots in .mcz archives; Iceberg integrates Git and uses Tonel text files.
  • The normal loop: edit, test, review the diff in Iceberg, commit, push, pull.
  • Ignore images and local files; rebuild from a baseline with a loading script.
  • Commands and screens here are read-only; the diff and merge programs are JavaScript stand-ins.

Next: Metacello, Baselines and Package Loading