# Meld Users Manual

## Introduction

### What is meld

Meld views differences between files and between directories. Meld makes it easy to isolate and merge these differences.

### Starting meld

#### Command line arguments

`meld`

- start meld with the new document dialog

`meld <file> <file> [file]`

- start meld with either a two way or three way comparison

`meld <dir> <dir> [dir]`

- start meld with either a two way or three way comparison

`meld <dir|file>`

- start meld with the source control browser

"<>" surround required arguments, "[]" surround optional arguments and "|" indicates a choice.

Run `meld --help` for a complete list of options

## File Comparison

### Starting

To compare files, choose File New and select the File Comparison tab. You can compare two or three files.

For two way comparisons the original is shown in the left pane and the modified version in the right pane by convention.

For three way comparisons, the original is shown in the centre pane and the left and right panes show the modified versions. By convention we put the locally modified file in the right pane.

### Change Summary

The location of the changes is summarised in the window margins at the far left and right. By default green marks insertions and deletions and blue marks changes.

You can jump to an individual change by clicking in the margin or using the scrollbar.

### Detailed View

Detailed differences are shown in the text and central pane. Inserted text is shown with a solid background. Lines containing changes are marked with a light background with the individual changes highlighted with a stronger colour.

The area between each file shows where each change occurs in the other file. You can scroll through the changes by rolling the mouse wheel over this area or with keyboard shortcuts Ctrl D, Ctrl E.

### Editing

You can edit the files as you would in a normal text editor. The differences will update automatically. Use Ctrl F to search and Ctrl G to repeat the last search.

You can also apply changes by clicking the merge buttons ("->" and "<-"). Holding Shift allows blocks to be deleted. Holding Control allows the current change to be inserted before or after the other change.

You can apply all the changes from a given file by right clicking a text pane and choosing Copy all left or Copy all right. You can also launch an external editor from this menu. Configure the external editor in Settings Preferences.

### Filtering

You can ignore certain types of differences in order to locate important differences. All these settings are available in the Text Filters section of the Preferences dialog.

#### Regular Expressions

When comparing files, each selected regular expression is run in turn over each line of input. Anything matching the expression is removed from the input.

See the python re module for more information on regular expressions

Differences are computed line-by-line so multiline regulare expressions will likely have unintended consequences.

#### Blank Lines

Changes which insert or remove blank lines can be ignored. This option is most useful in conjunction with one or more regular expression filters.

### Saving

When you have unsaved changes, a disk icon will appear beside the file name of the changed file. The tab label and window title also have an asterix after the file name.

To save a file, choose File Save, press Ctrl S, or press the toolbar save button. All of these save the currently focussed file (the file containing the edit cursor).

### Status Bar

The status bar shows the cursor location (line and column) and also progress messages as files are initially loaded and compared.

## Folder Comparison

### Starting

To compare directories, choose File New and select the Directory Comparison tab. You can compare two or three directories.

For two way comparisons the original is shown in the left pane and the modified version in the right pane by convention.

For three way comparisons, the original is shown in the centre pane and the left and right panes show the modified versions. By convention we put the locally modified file in the right pane.

### Change Summary

Similarly to the file comparison, the window margins mark file deletions, creations and modifications.

You can jump to an individual change by clicking in the margin or using the scrollbar.

### Detailed View

Modified files are highlighted with red, created files with green and deleted files with a strikethrough. See also dir_content_filtering

The file or folder most recently modified has a red dot superimposed on its icon. More detailed information such as file permission and modification time can be seen in the status bar when a file is selected.

Use the mouse or the the cursor keys Up, Down, Left and Right to navigate. Additionally Ctrl D and Ctrl E move to the next and previous modification respectively.

### Editing

Activate an item with double click or Return to start an individual file comparison.

Additional options are available from a right click context menu.

Use Shift+Click and Control+Click to select multiple items.

### Filtering

Often the initial comparison will contain too much spurious information. You can use filters to isolate the differences which are important to you.

#### Explicit Hiding

Use the toolbar button to hide an item (and all subitems for directories).

#### Case Sensitivity

By default filename comparisons are case sensitive. Use the toolbar button to toggle case sensitivty of filenames.

#### State Filtering

All items have a state which is one of:

- Modified (there is some content difference between files which are present)

- New (there is no content difference between present files, but the file is missing from at least one directory)

- Identical (all files have equal content and are all present)

Use the toolbar buttons to control which items are shown by their state.

In the current version, only files are filtered by state. Directories are always shown.

#### Name Filtering

Meld can hide certain filename patterns from the comparison using the toolbar buttons. Customise the file patterns that are hidden in the File Filters section of the Preferences dialog.

#### Content Filtering

If differences between files exist, but all differences match the active regular expressions specified in Text Filters section of the Preferences dialog, then the filename is not highlighted in red, but is insted italicised in regular font.

## Source Control

### Starting

To browse a working copy of a source control repository, choose File New and select the Version Control Browser tab.

The browser is used for examining and commiting or reverting local changes. It is not intended to be a complete source control client.

### Filtering

The browser can filter on four states. To show or hide all files in a particular state, select or deselect the corresponding toggle button in the toolbar.

Normal

- The file has not changed since it was checked out or committed.

Modified

- The file has been locally changed, added, or removed.

Non VC

- The file is non-version controlled: it exists locally but was not checked out from a repository.

Ignored

- The file is explicitly ignored e.g. though a `.cvsignore` file.

The Flatten toggle displays the directory listing as a plain list, showing all subdirectory contents together. This makes it easier to see several changes scattered in several directories or in a large tree. This is especially useful in conjunction with only the modified filter active.

### Viewing Differences

Activating an unmodified file opens it in the file viewer. Activating a modified file opens up a two way diff to examine your changes.

You can examine many changes at once using Shift+Click and Control+Click to select multiple items.

### Making Changes

The toolbar contains commands to perform the most common source control operations. These operations are also accessible through a context menu.

### Viewing Console

At the bottom of the source control window is an expander containing all the source control operations and their output. Click the expander bar to toggle between hiding and showing the console.

## Shortcut Keys

For more on shortcut keys, see the Desktop User Guide.

## Shortcuts for working with files and comparisons

Shortcut | Description
Ctrl N | Start a new comparison.
Ctrl S | Save the current document to disk.
Ctrl Shift S | Save the current document with a new filename.
Ctrl W | Close the current comparison.
Ctrl Q | Quit Meld.

## Shortcuts for editing documents

Shortcut | Description
Ctrl Z | Undo the last action.
Ctrl Shift Z | Redo the last undone action.
Ctrl X | Cut the selected text or region and place it on the clipboard.
Ctrl C | Copy the selected text or region onto the clipboard.
Ctrl V | Paste the contents of the clipboard.
Ctrl F | Find a string.
Ctrl G | Find the next instance of the string.
Ctrl D | Go to the next difference.
Ctrl E | Go to the previous difference.

## Shortcuts for view settings

Shortcut | Description
Escape | Stop the current comparison.
Ctrl R | Refresh the current comparison.
Ctrl Shift R | Reload the current comparison.

## Shortcuts for help

Shortcut | Description
F1 | Open Meld's user manual.