# 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 file comparison

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

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

`meld <dir|file>`

- start meld with the source control browser

"<>" demote required arguments, "[]" denote optional arguments and "|" a choice.

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

## File Comparison

### Starting

Use File...->New...->File Comparison to start a new file comparison. 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 Control+D, Control+E.

### Editing

You can edit the files as you would in a normal text editor. The differences will update automatically. Use Control+F to search and Control+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->Editor

### Filtering

You can ignore certain types of differences in order to locate important differences. All these settings are available from Settings->Preferences->Text Filters.

#### 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.

Save a file pressing Control+s, by selecting File->Save from the menu or by 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

Use File...->New...->Directory Comparison to start a new directory comparison. 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 Control+D and Control+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

You can hide selected filename patterns from the comparison using the toolbar buttons. Use Settings->Preferences->File Filters to customise the file patterns.

#### Content Filtering

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

## Source Control

### Starting

Use File...->New...->CVS Browser or File...->New...->SVN Browser to start browsing a working copy.

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:

- Normal (the file is unchanged since it was checked out)

- Non controlled (the file exists locally but was not checked out)

- Ignored (the file is explicitly ignored e.g. though .cvsignore)

- Modified (locally changed, added or removed)

If you have several changes scattered in several directories or in a large tree, the 'Recurse' tooggle is flattens the directory listing. 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.