Crystal User Manual

Table of Contents:

• Crystal's goal
• How to run Crystal
• Download and installation
• Preventing Crystal from asking for a password
• What Crystal displays
• Local state
• Relationship
• Action
• Guidance
• Configuration file format
• Making your repository available to your co-workers
• Making a copy of your repository
• Troubleshooting
• Log files
• Publications
• Acknowledgements
• Contacts

Goal: Increased developer awareness of conflicts

When two or more developers collaborate, it is possible for their independent changes to conflict — either syntactically as a version control conflict or behaviorally if the changes merge cleanly but have unintended interactions.

The Crystal tool informs each developer of the answer to the question, “Might my changes conflict with others' changes?”

Crystal monitors multiple developers' repositories. It informs each developer when it is safe to push her changes, when she has fallen behind and could pull changes from others or a central repository, and when changes other developers have made will cause a syntactic or behavioral conflict.

Crystal examines commits. It does not examine your working copy — your uncommitted modifications. The reason is that commits are more likely to be coherent and desired units of work, for which notification about (non-)conflicts is of value.

• If conflicts occur, Crystal informs developers early, so they may resolve these conflicts quickly. Long-established conflicts can be much harder to resolve.
• If changes are made without conflicts, Crystal gives developers confidence to merge their changes without fearing unanticipated side effects.

Download Crystal

How to run Crystal

To run Crystal, either double click the crystal.jar file or execute from the command line:

java -jar crystal.jar

Crystal runs as an icon in your task bar. Click on the icon to see the full client and more options.

Download and installation

Crystal has the following requirements:

• JRE (Java Runtime Environment).
• Mercurial, version 1.6 or later or Git.
• The more of your co-workers' repositories you have read access to, the more useful Crystal will be. However, Crystal can be useful even if you only have access to your repository's parent.

To install Crystal:

• Download crystal.jar. (The current version is 2.0.20111120. To learn the version of an executable, run java -jar crystal.jar --version or select the about menu in the GUI.)
• Run Crystal: java -jar crystal.jar
• The first time that you run Crystal, it will complain that your configuration file is invalid and give you instructions on how to fix it. You can do so either via a GUI that creates the configuration file for you, or by editing the configuration file directly. See below for the configuration file format.
• Restart Crystal.

Preventing Crystal from asking for a password

If accessing the remote repositories in your configuration file prompts you for a password, then Crystal will forward that prompt to you. Crystal accesses these repositories frequently — by default, every 10 minutes for each repository.

Depending on how you access your repositories, there are ways to get around entering your password every time:

If you use ssh to access the repositories, you can use the instructions for plink (comes with the Windows installation of Mercurial and Git) or instructions for ssh agent. If you use http or https to access the repositories, you can enter the passwords in plain text in your Mercurial or Git configuration file.

What Crystal displays

This is a screen shot of the main Crystal window.

Crystal displays four types of information: local state, relationship, possible action, and guidance.

Local state

The "local state", shown below the project name, describes the working copy. It shows a command that can be run on the working copy.

1. If there are uncommitted local changes, it shows hg commit
2. If there are unresolved conflicts, it shows hg fetch
3. Otherwise, it is blank

Relationship

There are seven possible relationships (plus two descriptors) between the developer's repository and that of a collaborate. This relationship determines the shape of the icon Crystal displays. Each relationship may come in one of three shadings.

Crystal shape	Meaning of the shape
	SAME: The repositories are in sync.
	AHEAD: Your repository has newer commits than the other one. You may consider pushing your changes or letting the owner know.
	BEHIND: The other repository has newer commits than yours. You may consider pulling changes to avoid later merges.
	MERGE: Each of the two repositories has commits not present in the other one, but they can be merged cleanly.
	TEXTUAL_X: Each of the two repositories has commits not present in the other one, and merging them will result in a textual conflict.
	BUILD_X: Each of the two repositories has commits not present in the other one, they can be merged textually cleanly, but merging them results in code that fails to build.
	TEST_X: Each of the two repositories has commits not present in the other one, they can be merged textually cleanly, but merging them results in code that fails tests.
	Crystal is in the process of refreshing this data.
	Crystal experienced an error in computing this relationship.

The icons' shading has the following meaning:

Icon shading	Meaning of the shading
Solid	You must be the one who affects this relationship, and you can do so now.
Partially saturated	You might be the one who affects this relationship, and you might be able to do so now or later.
Hollow	You cannot be the one who affects this relationship, neither now nor later.

In the task bar, Crystal displays the most severe relationship icon that appears anywhere in the full window.

Action

Holding the mouse over an icon displays a tool tip. At the top of the tool tip, Crystal shows the action the developer may perform, if one is available (e.g., hg commit, hg merge, hg fetch, and hg push).

Guidance

There are five types of guidance Crystal displays:

1. ommitter: the list of users whose changes are causing the relationship. Crystal displays this information in the tool tip.
2. hen: whether or not the developer can act right now to affect this relationship. The relationship icon is solid if the developer can act now, and hollow if the developer cannot act until later, after some other developer has performed an action.
3. apable: whether or not the developer must, might, or cannot act to affect the relationship. The relationship icon is solid if the developer must be the one to take action, solid but unsaturated if the developer might be the one to take action, and hollow if the developer cannot be the one to take action.
4. onsequences: the new relationship after the developer executes the available action. Crystal displays this information in the tool tip.
5. ase: Whether another developer may have an easier time affecting this relationship. Crystal does not yet display this information in the tool tip, but future versions will.

Configuration file format

The Crystal configuration file is an XML file that describes the locations of the scratch space, the hg executable, and the repositories Crystal monitors. On a Unix-like environment, it appears in ~/.conflictClient.xml. On a Windows environment, it appears in the user's home directory, e.g., %UserProfile%\.conflictClient.xml.

Here is an example valid configuration file:

<?xml version="1.0" encoding="UTF-8"?>
<ccConfig tempDirectory="/scratch/conflictClient/" refresh="60">
  <!-- First project uses dropbox to share repositories -->
  <project ShortName="MyFirstProject" Kind="HG" Clone="$HOME/Dropbox/projects/MyLocalFirstProjectRepo/" parent="MASTER">
    <source ShortName="MASTER" Clone="$HOME/Dropbox/projects/MASTER/MyLocalFirstProjectRepo/" commonParent="MASTER" />
    <source ShortName="Friend" Clone="$HOME/Dropbox/projects/Friend/MyLocalFirstProjectRepo" commonParent="MASTER" />
    <source ShortName="Enemy" Clone="$HOME/Dropbox/projects/Enemy/MyLocalFirstProjectRepo" commonParent="MASTER" />
  </project>
  <!-- Second project does not use dropbox to share repositories -->
  <project ShortName="MySecondProject" Kind="HG" Clone="$HOME/projects/MyLocalSecondProjectRepo/"
           parent="MASTER" compile="make" test="make test">
    <source ShortName="MASTER" Clone="ssh://user@host/path/to/second/project/repo/" commonParent="MASTER" />
    <source ShortName="Friend" Clone="https://user@host/path/to/friend/second/repo" commonParent="MASTER" />
  </project>
</ccConfig>

To be a valid XML file, it cannot have any whitespace before the <?xml ...?> element. A configuration file consists of a single XML element: ccConfig. This element has two attributes: tempDirectory and (optionally) refresh. These attributes specify the path to the scratch space and how often, in seconds, Crystal should attempt to refresh itself. ccConfig has a project child for each project that Crystal monitors.

The project XML element has 7 attributes; the first three are required and the last four are optional.

• ShortName: the name of the project that Crystal will display on the left side on the main window
• Kind: the DVCS; currently, must be HG
• Clone: the path to your local repository. This may be any address that is a valid argument to the hg clone command. Typically, this is a local path to a directory that contains a .hg directory.
• parent: the shortName of the repository that is your repository's parent; that is, the default place you push to and pull from. Crystal needs to know the parent to determine your possible actions; if you do not supply the parent attribute, Crystal will not report the action information.
• RemoteHG: necessary only if the --remotecmd option is necessary to specify the path to hg on the server where your local repository resides; the value of this element is passed directly to the hg command with the --remotecmd option.
• compile: a command to execute to compile the project, such as "make"
• test: a command to execute to run the project's tests, such as "make test"

The project element has a source child for each remote repository that Crystal should compare to your repository.

The source element has four attributes. The first two are required and the last two are optional.

• ShortName: the name of the repository that Crystal to displays above the relationship icon in the main window.
• Clone: the path to this repository. This can be any address that is a valid argument to hg clone.
• commonParent: the shortName of the repository that is the common parent between your repository and the repository this source element represents. Most often, the common parent is the master repository. Crystal needs to know the common parent to determine the guidance information; if you do not supply the commonParent attribute, Crystal will not report any guidance and all relationship icons will appear solid.
• RemoteHG: only necessary if the --remotecmd option is necessary to specify the path to hg on the server where the repository this source element represents resides; the value of this element is passed directly to the hg command with the --remotecmd option.

Making your repository available to your co-workers

The more of your co-workers' repositories you have read access to, the more useful Crystal will be. This section explains how to make your repositories (your clones) available to a co-worker.

If you and your co-worker have access to the same file system, then you can use the "File system sharing" technique. If you have access to a machine that runs a web server, then you can use the "Http sharing" technique. You can always use the "Dropbox sharing" technique.

File system sharing

If you and your co-worker have access to the same file system, then you can store your repository in a place where your co-worker can read it.

You can either grant your co-worker read permission to your repository, or you can copy your repository to a location that your co-worker can read.

Dropbox sharing

You can use the Dropbox file sharing service to share your repository with your co-workers. This approach has several benefits: changes are copied immediately, and the same technique works for all co-workers. For full details, see the document Sharing repositories using Dropbox.

Http sharing

The http sharing approach is often easier, but it only works if you have access to a machine that runs a web server. Either make your repository accessible via http, or periodically copy your repository to a location that is accessible via http. In other words, the location will be a directory that has a http: URL.

• To make your repository accessible via http, one way is to make a symbolic link from your ~/public_html (or similar) directory (this may require changing access permissions so the web server can read your repository).
• If you make a copy of your repository, then don't forget to make .../accessible-path/ and all subdirectories readable by the web server (example: chmod -R og+r .../accessible-path), and also enable the web server to show a directory listing to the hg client (example: add +Indexes to file .../accessible-path/.htaccess).

Making a copy of your repository

If you choose to make a copy of your repository in an accessible location, then the more frequently you update the copy, the more useful Crystal is. Here is a line you can place in your crontab file to automate the task:

# Update a public copy of a `.hg` directory every minute.
* * * * *	rsync -a .../path-to-repo/.hg .../accessible-path

The .hg directory will end up as .../accessible-path/.hg, and the path to the repository is just .../accessible-path.

The rsync program even permits the destination path to be on a different computer, in which case it looks like machinename:filename, for example barb.cs.washington.edu:/homes/gws/mernst/www/crystal-repositories/...

Troubleshooting

• If Crystal complains that it cannot load the .conflictClient.xml file and the error message contains "> > > null", your .conflictClient.xml file is invalid:
• Make sure there is a <?xml ... > element.
• Make sure the <?xml ... > element contains no blank lines or spaces before it.
• Make sure all the required elements are present.
• If Crystal reports that it can't run Mercurial or Git:
• Make sure you have the latest version of Mercurial. Crystal will let you know the oldest compatible version. Repositories created with newer versions do not always operate with older versions of the tool.
• If you created a symbolic link to your .hg directory, make sure it actually points where you think it does by browsing it.

Log files

Crystal maintains two log files to help with diagnosing unexpected problems. One is a plain text log that is easy to read (.conflictClientLog.log) and the other is an XML log that can be more easily analyzed programmatically (.conflictClientLog.xml). On a Unix-like environment, these appear in ~/. On a Windows environment, these appears in the user's home directory %UserProfile%\.

Publications

See the publications page for the most recent list of publications about Crystal.

Acknowledgements

This work is supported by Microsoft Research through the Software Engineering Innovation Foundation grant, by the National Science Foundation under Grant# 0963757 and Grant #0937060 to the Computing Research Association for the CIFellows Project, by the National Science and Engineering Research Council Postdoctoral Fellowship, and by IBM through a John Backus Award.

Contacts

Crystal is designed and developed by Yuriy Brun, Reid Holmes, Michael Ernst, and David Notkin.

Email us with any questions.