# Working With Files

## Creating New Files

File>New (shortcut: C+n) opens a new, empty, buffer. Another way to create a new file is to specify a non-existent file name when starting jEdit on the command line. A new file will be created on disk when the buffer is saved for the first time.

## Opening Files

File>Open (shortcut: C+o) displays a file system browser dialog box and loads the specified file into a new buffer.

Multiple files can be opened at once by holding down Control while clicking on them in the file system browser. The file system browser supports auto-completion; typing the first few characters of a listed file name will select the file.

More advanced features of the file system browser are described in .

The File>Recent Files menu lists recently viewed files. When a recent file is opened, the caret is automatically moved to its previous location in that file. The number of recent files to remember can be changed and caret position saving can be disabled in the General pane of the Utilities>Options dialog box; see .

The Utilities>Current Directory menu lists all files and directories in the current buffer's directory. Selecting a file opens it in a buffer for editing; selecting a directory opens it in the file system browser (see ).

Files that you do not have write access to are opened in read-only mode, where editing is not permitted.

jEdit supports transparent editing of GZipped files; if a file begins with the GZip magic number, it is automatically decompressed before loading and compressed when saving. To compress an existing file, you need to change a setting in the Utilities>Buffer Options dialog box; see for details.

## Saving Files

Changed made in a buffer do not affect the file on disk until the buffer is saved.

File>Save (shortcut: C+s) saves the current buffer to disk.

File>Save As renames the buffer and saves it in a new location. Note that using this command to save over another open buffer will close the other buffer, to stop two buffers from being able to share the same path name.

File>Save a Copy As saves the buffer to a different location but does not rename the buffer, and does not clear the modified flag. Note that using this command to save over another open buffer will automatically reload the other buffer.

File>Save All (shortcut: C+e C+s) saves all open buffers to disk, asking for confirmation first. The confirmation dialog can be disabled in the General pane of the Utilities>Options dialog box.

### Two-Stage Save

To prevent data loss in the unlikely case that jEdit should crash in the middle of saving a file, files are first saved to a temporary file named `#filename#save#`. If this operation is successful, the original file is replaced with the temporary file.

However, in some situations, this behavior is undesirable. For example, on Unix this creates a new i-node so while jEdit retains file permissions, the owner and group of the file are reset, and if it is a hard link the link is broken. The two-stage save feature can be disabled in the General pane of the Utilities>Options dialog box; see .

### Autosave and Crash Recovery

The autosave feature protects your work from computer crashes and such. Every 30 seconds, all buffers with unsaved changes are written out to their respective file names, enclosed in hash (#) characters. For example, `program.c` will be autosaved to `#program.c#`.

Saving a buffer using one of the commands in the previous section automatically deletes the autosave file, so they will only ever be visible in the unlikely event of a jEdit (or operating system) crash.

If an autosave file is found while a buffer is being loaded, jEdit will offer to recover the autosaved data.

The autosave interval can be changed in the Autosave and Backup pane of the Utilities>Options dialog box; see .

### Backups

The backup feature can be used to roll back to the previous version of a file after changes were made. When a buffer is saved for the first time after being opened, its original contents are backed up under a different file name.

The behavior of the backup feature is specified in the Autosave and Backup pane of the Utilities>Options dialog box; see .

The default behavior is to back up the original contents to the buffer's file name suffixed with a tilde (~). For example, a file named `paper.tex` is backed up to `paper.tex~`.

- The Max number of backups setting determines the number of backups to save. Setting this to zero disables the backup feature. Settings this to more than one adds numbered suffixes to file names. By default only one backup is saved.

- If the Backup directory setting is non-empty, backups are saved in that location (with the full path to the original file under it). Otherwise, they are saved in the same directory as the original file. The latter is the default behavior.

- The Backup filename prefix setting is the prefix that is added to the backed-up file name. This is empty by default.

- The Backup filename suffix setting is the suffix that is added to the backed-up file name. This is ~ by default.

- Backups can optionally be saved in a specified backup directory, instead of the directory of the original file. This can reduce clutter.

- The Backup on every save option is off by default, which results in a backup only being created the first time a buffer is saved in an editing session. If switched on, backups are created every time a buffer is saved.

## Line Separators

Unix systems use newlines (`\n`) to mark line endings in text files. The MacOS uses carriage-returns (`\r`). Windows uses a carriage-return followed by a newline (`\r\n`). jEdit can read and write files in all three formats.

The line separator used by the in-memory representation of file contents is always the newline character. When a file is being loaded, the line separator used in the file on disk is stored in a per-buffer property, and all line-endings are converted to newline characters for the in-memory representation. When the buffer is consequently saved, the value of the property replaces newline characters when the buffer is saved to disk.

There are several ways to change a buffer's line separator:

- In the Utilities>Buffer Options dialog box. See .

- By clicking the line separator indicator in the status bar. See .

- From the keyboard, if a keyboard shortcut has been assigned to the Toggle Line Separator command in the Shortcuts pane of the Utilities> Options dialog box. By default, this command does not have a keyboard shortcut.

By default, new files are saved with your operating system's native line separator. This can be changed in the Encodings pane of the Utilities>Options dialog box; see . Note that changing this setting has no effect on existing files.

## Character Encodings

A character encoding is a mapping from a set of characters to their on-disk representation. jEdit can use any encoding supported by the Java platform.

Buffers in memory are always stored in `UTF-16` encoding, which means each character is mapped to an integer between 0 and 65535. `UTF-16` is the native encoding supported by Java, and has a large enough range of characters to support most modern languages.

When a buffer is loaded, it is converted from its on-disk representation to `UTF-16` using a specified encoding.

The default encoding, used to load files for which no other encoding is specified, can be set in the Encodings pane of the Utilities> Options dialog box; see . Unless you change this setting, it will be your operating system's native encoding, for example `MacRoman` on the MacOS, `windows-1252` on Windows, and `ISO-8859-1` on Unix.

An encoding can be explicitly set when opening a file in the file system browser's Commands>Encoding menu.

Note that there is no general way to auto-detect the encoding used by a file, however jEdit supports "encoding detectors", of which there are some provided in the core, and others may be provided by plugins through the services api. From the encodings option pane , you can customize which ones are used, and the order they are tried. Here are some of the encoding detectors recognized by jEdit:

- BOM: `UTF-16` and `UTF-8Y` files are auto-detected, because they begin with a certain fixed character sequence. Note that plain UTF-8 does not mandate a specific header, and thus cannot be auto-detected, unless the file in question is an XML file.

- XML-PI: Encodings used in XML files with an XML PI like the following are auto-detected:

      <?xml version="1.0" encoding="UTF-8">

- html: Encodings specified in HTML files with a `content=` attribute in a `meta` element may be auto-detected:

      <html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8">

- python: Python has its own way of specifying encoding at the top of a file.

      # -*- coding: utf-8 -*-

- buffer-local-property: Enable buffer-local properties' syntax (see ) at the top of the file to specify encoding.

      #  :encoding=ISO-8859-1:

The encoding that will be used to save the current buffer is shown in the status bar, and can be changed in the Utilities>Buffer Options dialog box. Note that changing this setting has no effect on the buffer's contents; if you opened a file with the wrong encoding and got garbage, you will need to reload it. File>Reload with Encoding is an easy way.

If a file is opened without an explicit encoding specified and it appears in the recent file list, jEdit will use the encoding last used when working with that file; otherwise the default encoding will be used.

### Commonly Used Encodings

While the world is slowly converging on UTF-8 and UTF-16 encodings for storing text, a wide range of older encodings are still in widespread use and Java supports most of them.

The simplest character encoding still in use is ASCII, or American Standard Code for Information Interchange. ASCII encodes Latin letters used in English, in addition to numbers and a range of punctuation characters. Each ASCII character consists of 7 bits, there is a limit of 128 distinct characters, which makes it unsuitable for anything other than English text. jEdit will load and save files as ASCII if the `US-ASCII` encoding is used.

Because ASCII is unsuitable for international use, most operating systems use an 8-bit extension of ASCII, with the first 128 values mapped to the ASCII characters, and the rest used to encode accents, umlauts, and various more esoteric used typographical marks. The three major operating systems all extend ASCII in a different way. Files written by Macintosh programs can be read using the `MacRoman` encoding; Windows text files are usually stored as `windows-1252`. In the Unix world, the `8859_1` character encoding has found widespread usage.

On Windows, various other encodings, referred to as code pages and identified by number, are used to store non-English text. The corresponding Java encoding name is `windows-` followed by the code page number, for example `windows-850`.

Many common cross-platform international character sets are also supported; `KOI8_R` for Russian text, `Big5` and `GBK` for Chinese, and `SJIS` for Japanese.

## The File System Browser (FSB)

Utilities>File System Browser displays the file system browser. By default, the file system browser is shown in a floating window. This window can be docked using the commands in its top-left corner popup menu; see .

The FSB can be customized in the Utilities>Options dialog box; see .

### Navigating the File System

The directory to browse is specified in the Path text field. Clicking the mouse in the text field automatically selects its contents allowing a new path to be quickly typed in. If a relative path is entered, it will be resolved relative to the current path. This text field remembers previously entered strings; see . The same list of previously browsed directories is also listed in the Utilities>Recent Directories menu; selecting one opens it in the file system browser.

To browse a listed directory, double-click it (or if you have a three-button mouse, you can click the middle mouse button as well). Alternatively, click the disclosure widget next to a directory to list its contents in place. To browse higher up in the directory hierarchy, double-click one of the parent directories in the parent directory list.

Files and directories in the file list are shown in different colors depending on what glob patterns their names match. The patterns and colors can be customized in the File System Browser>Colors pane of the Utilities>Options dialog box.

The Path: Text Box can be used to navigate to a specific directory. Environment variables are expanded here, allowing for both `$VARNAME` or `%VARNAME%` syntax.

`A+Up` is a keyboard shortcut that brings you to the parent directory.

`A+Left` and `A+Right` navigate back and forward through the visited directory stacks, in a Netscape/Konqueror/IE like fashion.

To see a specific set of files only (for example, those whose names end with `.java`), enter a glob pattern in the Filter text field. This text fields remembers previously entered strings. See for information about glob patterns.

Unopened files can be opened by double-clicking (or by clicking the middle mouse button). Open files have their names underlined, and can be selected by single-clicking. Holding down Shift while opening a file will open it in a new view.

Clicking a file or directory with the right mouse button displays a popup menu containing various commands.

The file list sorting algorithm used in jEdit handles numbers in file names in an intelligent manner. For example, a file named `section10.xml` will be placed after a file named `section5.xml`. A conventional letter-by-letter sort would have placed these two files in the wrong order.

### The Tool Bar

The file system browser has a tool bar containing a number of buttons. Each item in the Commands menu (described below) except Show Hidden Files and Encoding has a corresponding tool bar button.

### The Commands Menu

Clicking the Commands button displays a menu containing the following items:

- Parent Directory - moves up in the directory hierarchy. The Alt+Left arrow keyboard shortcut achieves the same thing.

- Reload Directory - reloads the file list from disk. F5 does this also.

- Root Directory - on Unix, goes to the root directory (`/`). On Windows and MacOS X, lists all mounted drives and network shares. The forward slash (/) achieves this too.

- Home Directory - displays your home directory. Keyboard shortcut: ~

- Directory of Current Buffer - displays the directory containing the currently active buffer. Shortcut: -

- New File (Ctrl+N) - opens new, empty, buffer in the current directory. The file will not actually be created on disk until the buffer is saved.

- New Directory - creates a new directory after prompting for the desired name.

- Search in Directory - displays the search and replace dialog box set to search all files in the current directory. If a file is selected when this command is invoked, its extension becomes the file name filter for the search; otherwise, the file name filter entered in the browser is used. See for details.

- Show Hidden Files - toggles if hidden files are to be shown in the file list.

- Encoding - a menu for selecting the character encoding to use when opening files. See .

### The Plugins Menu

Clicking the Plugins button displays a menu containing plugin commands. For information about plugins, see .

### The Favorites Menu

Clicking the Favorites button displays a menu showing all files and directories in the favorites list. The Add to Favorites item adds the currently selected file to the favorites list. If nothing is selected, the current directory is added. To remove a file from the favorites, invoke Edit Favorites, which will show the favorites list in the file system view, then select Delete from the right-click menu of the entry you want to remove.

### Keyboard Shortcuts

Completion behaves differently in file dialogs than in the stand-alone file system browser window.

In the file dialog, keyboard input goes in the file name field by default. Pressing Enter opens the file or directory path that is either fully or partially entered in the file name field. Typing the first few characters of a file's name selects that file. If the file name field is empty and nothing is selected, / lists the root directory on Unix and the list of drives on Windows. There are two handy abbreviations that may be used in file paths: ~ expands to the home directory, and - expands to the current buffer's directory.

For example, to open a file `/home/slava/jEdit/doc/TODO.txt`, you might enter `~/j/d/to`.

In the stand-alone file system browser, keyboard input is handled slightly differently. There is no file name field, instead shortcuts are active when the file tree has keyboard focus. Additionally, pressing /, ~ or - always immediately goes to the root, home and current buffer's directory, respectively.

## Reloading From Disk

When a view is brought to the foreground, jEdit checks if any open buffers were modified on disk by another application. All affected buffers are listed in a dialog box. By default, buffers without unsaved changes are automatically reloaded. This feature can be disabled, or changed to prompt if files should be reloaded first, in the General pane of the Utilities>Options dialog box; see .

File>Reload can be used to reload the current buffer from disk at any other time; a confirmation dialog box will be displayed first if the buffer has unsaved changes.

File>Reload All discards unsaved changes in all open buffers and reload them from disk, asking for confirmation first.

## Task Monitor, and background I/O tasks

To improve responsiveness and perceived performance, jEdit executes all buffer input/output tasks asynchronously. Plugins should do the same. When a task such as this is in progress, the status bar should display the number of running tasks and an icon that spins. If you do not see this, you can add the widget from the .

The Utilities>Troubleshooting> Task Monitor command displays a window with more detailed status information and progress meters for each task. By default, the Task Monitor is shown in a floating window. This window can be docked using the commands in its top-left corner popup menu; see . Tasks can be aborted in this window, however note that aborting a buffer save can result in data loss.

## Printing

File>Print (shortcut: C+p) prints the current buffer.

File>Page Setup displays a dialog box for changing your operating system's print settings, such as margins, page size, print quality, and so on.

The print output can be customized in the Printing pane of the Utilities>Options dialog box; see . The following settings can be changed:

- The font to use when printing.

- If a header with the file name should be printed on each page.

- If a footer with the page number and current date should be printed on each page.

- If line numbers should be printed.

- If the output should be color or black and white.

- The tab size to use when printing - this will usually be less than the text area tab size, to conserve space in the printed output.

- If folded regions should be printed.

## Closing Files and Exiting jEdit

File>Close (shortcut: C+w) closes the current buffer. If it has unsaved changes, jEdit will ask if they should be saved first.

File>Close All (shortcut: C+e C+w) closes all buffers. If any buffers have unsaved changes, they will be listed in a dialog box where they can be saved or discarded. In the dialog box, multiple buffers to operate on at once can be selected by clicking on them in the list while holding down Control. After all buffers have been closed, a new untitled buffer is opened.

File>Exit (shortcut: C+q) will completely exit jEdit, prompting if unsaved buffers should be saved first.