The topic of today sounds pretty technical, but it is one that has a great impact on your work, if you are a developer using Git. This post outlines two fundamentally different methods for examining Git changes with Kaleidoscope. An appendix illustrates how to combine your Git app of choice with either method.
Observing Change
At the end of the day, development work is all about making change, typically to multiple files in a project. Git is a system very popular among developers to manage changes and keep many versions of your files. Maybe you are using an app like Tower, Fork, or Gitfox, that helps you deal with Git. Or you are using the git command line suite. Either way, the content below is relevant if you are using Git.
Kaleidoscope is a diff and merge tool. In the development context, its purpose is to support you deal with change, monitor change, and help with potential problems arising from multiple changes to the same thing. There are multiple reasons to inspect change as part of your work. Unless you are solely using a web service like GitHub to inspect those changes, you are faced with the challenge of making those changes digestible.
When working locally, git difftool is the command of choice to inspect changes, as it prepares git changes to be viewed by the user. Git can integrate with third-party tools for diffing and merging, knowing that different users have different needs. This is where Kaleidoscope comes into play. Kaleidoscope can be set as difftool and mergetool in Git terminology. This means that git can use Kaleidoscope to visualize change or to help with merging. And Git apps like Tower use git difftool to visualize changes in Git, either directly or by integrating with specialized apps like Kaleidoscope.
The difftool part brings us to today’s topic: inspecting Git changes to multiple files in Kaleidoscope.
Kaleidoscope Changesets
Kaleidoscope has a special mode to look at changes in multiple files, something we call changeset. This is the default mode when used with git difftool. In that mode, we show a sidebar that lists all files that have been changed as part of a changeset. The content area shows whatever is selected in the sidebar. It can be a changed file, or one added, removed or moved to a different path, as part of that changeset.
The sidebar shows all files that have been changed, added, deleted, or moved. The content area shows changes in the file selected in the sidebar.
A lot of time, when working on a project, you don’t really care too much about the file structure. You are interested in the parts that have changed, the files. Kaleidoscope shows the directory structure of those changed files as headers in the sidebar.
You use the sidebar to quickly skip through all changed files. If there are too many files to cope with comfortably, such as when comparing entire branches or tags, there are multiple helpful features to filter the list, see the bottom-left area of the window.
Folder Comparison for Git
But at times, you may be interested in how changes to a git repository affect the structure of files and directories. For those cases, we have an option to compare the before and after of a git change using the Folder Comparison in Kaleidoscope.
This is where the magic --dir-diff (or short -d) option comes in for git difftool. As the name suggests, --dir-diff opens a directory comparison, not a changeset.
By default, Kaleidoscope expands all folders that contain changes, while leaving all other ones closed. That means, you get a super quick overview of all changes.
--dir-diff option, which gives you a comparison of two folders, exposing the structure of all changed files.From there, double-click any file to view changes to that file in a new Kaleidoscope document, tabbed into the current window.
Live Updates
Another important aspect in a particular scenario is getting live updates in Kaleidoscope while making changes.
There are two main reasons to inspect changes:
- You may inspect changes after they have been committed to Git. This happens when comparing two commits, branches, tags, … The changes have already happened to the repository, you are just reviewing what has happened before, likely to gain additional insight.
- When making changes across multiple files, it makes a lot of sense to review those changes in a different context before committing those changes to the repository. When just typing
git difftool(with no extra parameters) in Terminal, Kaleidoscope shows you all uncommitted changes to your working copy, so you can review them before committing them. The important bit here is that the B side in Kaleidoscope shows you the files in your working copy, meaning you can still modify those files. You can choose to revert changes by copying the relevant part from A to B.
Kaleidoscope changesets always had the capability to update live as you were making changes to the B side, either within Kaleidoscope or in your favorite text editor. As of Kaleidoscope 4.5, the Git Folder Comparison has the same ability. Kaleidoscope watches the entire directory structure and reloads files as they are being changed on disk. This means you can now review and correct your changes before committing, and keep Kaleidoscope open to see all changes in real-time.
Critical caveat: Kaleidoscope can only detect changes to files that are already shown either in the changeset or the folder comparison. As explained in the introduction, git difftool prepares the content to be sent to Kaleidoscope, and copies files to a temporary location. This is a one-off operation, so Kaleidoscope has no knowledge of any other files that exist in your repository.
Summary
There are two ways to look at changes to your Git repository, one evolves around a list of changed files and immediately shows content, the other one is focusing on the directory structure. Both are very capable and can be very helpful at times, but you need to decide what works best in your workflow.
Which one gets used is controlled by the --dir-diff (or -d) option of git difftool. As the name suggests, the –dir-diff option gives you the directory diff whereas leaving it off gives you the other way, the file list, called changeset in Kaleidoscope.
Appendix: Using Kaleidoscope with Git apps
Using a GUI app as a frontend to Git is very popular, so here are some recommendations on how to combine them with Kaleidoscope.
Tower
Like many other Git apps, Tower allows configuring a Diff and Merge tool in Settings. But if you look closer, you see the Perform directory diff checkbox. Turns out this toggles the --dir-diff option. This is the default being used when using the various Diff Tool or DIFFTOOL buttons in Tower.
For added convenience, bring up the contextual menu on a branch in the sidebar, and select Compare “<branch name>” with… This will show the following sheet, allowing you to select the two branches to be compared, with the first one being prefilled. Note the repeated Perform Directory Diff checkbox. The Tower folks realized that this is an option you may want to change occasionally, depending on the kind of comparison your are aiming for.
--dir-diff on the fly.Fork
Fork is a very capable Git client with a very special trick up its sleeves: it allows creating custom commands that can be attached to various menus. Here’s a screenshot of the Settings window, showing a few custom commands we created.
The selected one (Compare Branches using Kaleidoscope) runs this simple shell script to compare two arbitrary branches:
git difftool $1{ref} $2{ref}As we learned above, we could simply add -d after difftool to get a folder comparison. Here’s what it looks like to use that command:
Other Apps
Many other Git apps allow setting a custom difftool or mergetool and quite a few explicitly support Kaleidoscope. However, other apps we know only allow comparing single files using an external tool, not entire commits. Are you aware of other Git apps that support inspecting changes to multiple files using git diftool? Let us know…
Are you the creator of a Git tool that should integrate with Kaleidoscope? Please do get in touch, we’d love to collaborate!
