Pharo stores its source code in memory (by default) or in a snapshot of the memory when we save a Pharo image. This makes it complicated to manage source code in the long term or to collaborate with others.
In order to be able to save some source code in readable files, Pharo includes some textual export formats. This page will explain the main export formats used to save code in VCS such as git.
This page will present formats from the most recommended for new projects to the less recommended.
| Tonel | FileTree metadata less | FileTree metadata full | |
|---|---|---|---|
| Work out of the box since Pharo | 6.1 | 4 | 3 |
| Older version supported after update | 4 | 4 | 3 |
| Export granularity | Class | Method | Method |
| Works well on windows | ✅ | ❌ | ❌ |
| Easy to merge two branches | ✅ | ✅ | ❌ |
| Takes a reasonable space on file system | ✅ | ❌ | ❌ |
| Works with Iceberg | ✅ | ✅ | ❌ |
| Works with Monticello | ✅ | ✅ | ✅ |
| Pharo Version | FileTree metadata full | FileTree metadata less | Tonel |
|---|---|---|---|
| 3 | ✅ | ❌ | ❌ |
| 4 | ✅ | ✅ | Update Metacello + Install Tonel |
| 5 | ✅ | ✅ | Update Metacello + Install Tonel |
| 6.0 | ✅ | ✅ | Update Metacello + Install Tonel |
| 6.1 | ✅ | ✅ | ✅ |
| 7 | ✅ | ✅ | ✅ |
| 8 | ✅ | ✅ | ✅ |
Tonel (https://github.com/pharo-vcs/tonel) is an export format introduced in Pharo 6.1.
It creates one file by class or extended class and works well on Windows (compared to file tree).
Pros
- Works well on Windows
- Not much space lost because of small files
- Export readable files
- No problem during merge because of metadata
Cons
- Works out of the box since Pharo 6.1.
- Since the format is more recent than the others, some edges cases might cause trouble. (It rarely happens)
Tonel works out of the box in Pharo 6.1 and higher. But it is possible to make it work in Pharo 4 to 6.0 by updating Metacello and installing Tonel.
Metacello new
baseline: 'Metacello';
repository: 'github://Metacello/metacello:pharo-6.1_dev/repository';
get.
Metacello new
baseline: 'Metacello';
repository: 'github://Metacello/metacello:pharo-6.1_dev/repository';
onConflict: [:ex | ex allow];
load.
Metacello new
repository: 'github://pharo-vcs/tonel';
baseline: 'Tonel';
load.FileTree (https://github.com/dalehenrich/filetree) is the first export format that was integrated in the goal to use Pharo with Git. The first version had a lot of metadata (see section Filetree metadata full), the second was a new version with metadata less format.
This format exports one file per method. This can cause trouble with Windows because Windows has a maximum path and file name length of 255 characters. This limit can easily be reached with FileTree.
Another problem of the FileTree format is that most Pharo's methods are short and creating one file by method waste a lot of space because the physical representation of files on a drive has a minimal size (4 KiB on NTFS file systems) that is reached by most of Pharo's method.
Its advantage compared to FileTree metadata full is that there is no problem during the merge of the source code thanks to the absence of metadata.
Pros
- Easy to browse the history of a method
- Present since Pharo 4 out of the box
- No problem during merge because of metadata
Cons
- Cause trouble on Windows
- Waste space on the file system
FileTree metadata less is supported out of the box since Pharo 4.0 and cannot easily be used in older Pharo versions.
FileTree metadata full (https://github.com/dalehenrich/filetree )is the ancestor of FileTree metadata less and works in the same way but also export a lot of metadata relating to the commits such has a commit message (different from the one of the VCS), the timestamp of the method compilation, etc.
This simplifies the tooling because the tools can get some information from the metadata instead of the VCS but it also creates a lot of trouble while merging two branches using this format.
Merges can be eased via this project: https://github.com/ThierryGoubier/GitFileTree-MergeDriver
This format can be used via Monticello but not via Iceberg. Iceberg will ignore the format and export in FileTree metadata less.
Pros
- Easy to browse the history of a method
- Present in most Pharo versions out of the box
Cons
- Cause trouble on Windows
- Waste space on the file system
- Hard to merge two branches because of metadata
- Does not work with Iceberg, the default git tool since Pharo 7
This format works out of the box in most Pharo versions.