: [[image:iciclesimage]]

|| *Previous:*  [[Icicles - Buffer-Name Input]] || '''[[Icicles]]''' || IciclesIndex || *Next:* [[Icicles -  Persistent Completions]] ||

----




== File-Name Input and Locating Files Anywhere ==

Emacs offers two main functions for reading [[minibuffer]] input with
[[completion]]: `completing-read' and `read-file-name'.  '''Icicles''' uses
both of these, and it enhances each of them in various ways for
use in your own EmacsLisp code. These two functions can each be used to read file-name input, but
they do so in very different ways.

This section provides a reminder description of these two
functions, and then it describes the main '''Icicles''' [[command]]s that
read file names.

You do not need to use these '''Icicles''' commands to get the general benefits
of '''Icicles''' enhancements to `completing-read' and `read-file-name'.
What these commands offer are additional benefits.











[:RemappingVanillaFileCommands]
=== Remapping Vanilla File Commands to Icicles File Commands ===

By default, that is, if you do not change the value of [[user option]] '''`<tt>[[Icicles - Customization and General Tips#icicle-top-level-key-bindings|icicle-top-level-key-bindings]]</tt>'''', some commonly used Emacs commands
for accessing files are remapped to '''Icicles''' commands.  For
example, command `find-file', is by default remapped in ''Icicle''
mode to [[multi-command]] `icicle-file'.  '''Remapping''' means that any
keys, such as `C-x C-f', that would normally be bound to
`find-file' are instead bound to `icicle-file' when you are in
''Icicle'' mode.

Consult `icicle-top-level-key-bindings' to see how this works.  In
particular, note that if you normally bind a different command to
one of the keys mentioned here then the corresponding remapping in
`icicle-top-level-key-bindings' will not have the advertised
effect.

For example, if you normally use the key bindings provided by
library ##ffap.el## (FindFileAtPoint), meaning that you invoke
command `ffap-bindings', then for you `C-x C-f' is bound to
`find-file-at-point', not `find-file'.  By default, option
`icicle-top-level-key-bindings' does not remap
`find-file-at-point' to `icicle-file', so even in ''Icicle'' mode `C-x C-f' remains bound to `find-file-at-point'.  If you want `C-x C-f'
to be bound to `icicle-file', then change the `find-file' entry in
`icicle-top-level-key-bindings' (or add another entry for
`find-file-at-point').

What has just been pointed out for '''Icicles''' file commands applies
more generally to all ''Icicle''-mode command remapping provided by
option `icicle-top-level-key-bindings'.












[:KeysBoundDynamicallyForFileNameInput]
=== Action Keys Bound Dynamically During File-Name Input ===

In addition to the usual '''Icicles''' key bindings, during file-name completion the '''Icicles''' commands that read file names bind the
following keys dynamically in the minibuffer keymaps, so you can
use them while to perform various operations on the fly when you
input a file name.  These minibuffer bindings are also available for [[BookmarkPlus#AutofileBookmarks|autofile bookmark]] commands.

[:icicle-up-directory]
* '''`C-backspace'''' (`icicle-up-directory') to navigate up the directory hierarchy.  It removes the last directory component (and any partial file name) from your minibuffer input.  (For Emacs versions before Emacs 22, this feature is available only for completion of absolute file names.)

[:icicle-make-directory]
* '''`##C-c +##'''' (`icicle-make-directory') to create a directory on the
fly.

* '''`S-delete'''' to delete the file named by the current completion candidate.

[:icicle-all-candidates-list-alt-action]
* '''`##M-|##'''' (`icicle-all-candidates-list-alt-action') to open [[Dired]] on
the currently matching file names.  That is, it opens a special
Dired buffer that contains ''only'' the matching files.  You are
prompted for the Dired buffer name.  See [[Icicles - More About Multi-Commands#AlternativeActions|Alternative Actions]].


[:icicle-bookmark-file-other-window]
* '''`C-x m'''' (`icicle-bookmark-file-other-window') to visit a
bookmarked file or directory.  This is available only if you use
library '''[[Bookmark+]]''' (<tt>[[bookmark+.el]]</tt>).  It is a [[multi-command]], so you can
actually visit any number of file bookmarks.  When finished, you
can continue with non-bookmark file-name completion.


* '''`##C-x a +##'''' or '''`C-x a -'''' to add or remove tags for a file.  These
are [[http://delicious.com|delicious]]-style tags -- any labels you like.  If there is not
already an autofile bookmark for the file, then one is created.
(The autofile bookmark is where the tags are persisted.)  You need
library '''[[Bookmark+]]''' for this feature.  See also
[[Icicles - Bookmark Enhancements#TaggingFiles|tagging files]].

* '''`C-x a a'''' to bookmark a file, that is, to create an autofile
bookmark.  This is the same as `##C-x a +##' and `C-x a -', except
that it does not prompt you for tags to add or remove.  You need
library '''[[Bookmark+]]''' for this feature.

* '''`##C-x C-t *##'''' to narrow the current file-name completion
candidates to those that are tagged with ''all'' of the tags you
specify.  You are prompted for the tags.

* '''`##C-x C-t +##'''' -- same as `##C-x C-t *##', except it narrows to the
files tagged with ''any'' of the specified tags.

* '''`##C-x C-t % *##'''' to narrow the candidates to those whose tags ''all''
match a specified regexp.  You are prompted for the regexp.

* '''`##C-x C-t % +##'''' -- same as `##C-x C-t % *##', except it narrows to the
files that have ''any'' matching tag.



In many cases for '''Icicles''' multi-commands that read a file name,
you can use '''`M-n'''' to pick up the file name at [[point]], or if none
then the name of the file you are currently visiting.


'''Note:''' Whether a command supports file-name ''globbing wildcards''
such as `##*##' is independent of whether it uses `read-file-name' or
`completing-read'.  It is the command itself that offers such
support or not.  Globbing takes place only after the file name (with
wildcards) is read.  All '''Icicles''' commands that visit files (all of
the commands mentioned in this section) let you use globbing wildcards.  Remember also that file-name globbing, with
its special wildcards, has nothing to do with regexp completion
matching. See [[Icicles - Special Characters in Input Patterns]] for more
information about file-name globbing.









[:read-file-name]
=== Function `read-file-name' ===

Function '''`read-file-name'''' uses '''[::relative file-name completion]'''.

It is specialized for file-name input with
completion.  It knows about files and file names for your current
platform.  It knows about Emacs remote file name syntax ([[TrampMode|Tramp]],
Ange FTP).  And starting with Emacs 23, `TAB' also completes
environment variables during `read-file-name' completion.

Using `read-file-name' is the most flexible way to
read a file name in Emacs, and it is the traditional way.  Unless
stated otherwise, "''file-name completion''", even in the
'''Icicles''' doc, refers to `read-file-name' completion.

When `read-file-name' reads input, only the file name itself, not
the directory portion, is used for matching.  The directory is
understood to be the directory that is present in the minibuffer, or the value of variable `<tt>[[default directory|default-directory]]</tt>' (which
you can change using command `cd', for instance) if there is no directory there.

Whether the value of `default-directory' is automatically inserted in the minibuffer is controlled by user option `insert-default-directory'.  But if you do not change the
directory seen in the minibuffer then the behavior is the same whether or not the `default-directory' name is present in the
minibuffer: it is the assumed directory.  If you prefer, you can delete the directory name
first, using `M-k'.

With `read-file-name', you can thus use [[apropos completion]] to match a file-name ''substring'', without needing to prefix the
substring with `'''<tt>.*</tt>'''' in the minibuffer.  For example, to
match the file named `##favorite-foo-file.bar##' in directory
`/some/path/to/my/', you need ''not'' use `##/some/path/to/my/.*foo##'; it
is sufficient to use either `foo' or `/some/path/to/my/foo'.















[:completing-read]
[:absolute file-name completion]
=== Function `completing-read' ===

Function '''`completing-read'''' is a general function for reading input
with completion.  It is ''not'' specially designed for reading file
names.  It knows nothing about files and file names. It knows
nothing about remote file-name syntax.  When `completing-read' reads input, it makes no use of
`default-directory'.  The completion candidates are treated as
simple strings; they are not really treated as file names.

'''Icicles''' commands that use `completing-read' to read a file name typically
read an ''absolute'' name, that is, a name that includes the directory
portion.  This means that you can match against ''any part'' of the
full name, including any ''directory'' components.  The directory
portions of the candidate file names need not be the same -- you
can thus complete against a set of files in ''multiple'' directories.













[:ReadingFileNames]
[:IciclesCommandsThatReadFileNames]
=== Icicles Commands that Read File Names ===

'''Icicles''' commands that use `read-file-name' include all [[multi-command]]s,
such as `icicle-find-file', that are defined using
'''`icicle-define-file-command''''.  Vanilla Emacs command `find-file'
is another example of a command that uses `read-file-name'.

'''Icicles''' commands that use `completing-read' to read file names include the
multi-commands `icicle-find-file-absolute', `icicle-find-file-in-tags-table', `icicle-recent-file', `icicle-locate', `icicle-locate-file', and `icicle-locate-file-no-symlinks'.  These are defined using
'''`icicle-define-command'''', not `##icicle-define##''##-file##''##-command##'.

There are also `-other-window' versions of all of the '''Icicles'''
commands that read file names.


[:LocateByDate]
The '''Icicles''' commands that use `completing-read' to read file names have an
additional feature: you can use a [[prefix argument]] to tell them to
combine the last modification date with the file name, as a
[[multi-completion]]. This means that you can easily look up files whose modification
time or date matches some (regexp) criterion, such as being
sometime in July 2008.

When using a command that reads an absolute file name, remember
that, to save space, you can use '''`##C-x .##'''' to toggle hiding of the
common match portions of the candidates in `*Completions*'.  This
portion is often a long directory substring.

Because this generally facilitates the use of absolute file-name
commands, by default '''Icicles''' ''automatically does this'' for you.  You
can unhide the common-match portion by hitting the toggle `<tt>C-x .</tt>'.

You can control which commands automatically turn on hiding of the
expanded common match, by adding/removing property
'''`icicle-hide-common-match'''' to/from the command symbol.  For
example, if you do not want `icicle-locate-file' to hide the
common match then add this to your [[init file]] (##~/.emacs##):

    (put 'icicle-locate-file 'icicle-hide-common-match nil)

On the other hand, you can make any command hide the common match
by putting a non-`nil' value on its symbol.













[:icicle-file]
[:icicle-find-file]
[:icicle-find-file-absolute]
==== `icicle-file', `icicle-find-file', `icicle-find-file-absolute' ====

[[multi-command|Multi-command]] '''`icicle-file'''' is bound, by default, to '''`C-x C-f'''' in ''Icicle''
mode, thus taking the place of `find-file'.  It combines multi-commands
`icicle-find-file' and `icicle-find-file-absolute'.  With ''no''
prefix argument, it matches ''relative'' file names; with a [[prefix argument]], it matches ''absolute'' names (as ordinary strings).  With a ''negative'' prefix argument, you
can match also the last modification date.

An additional feature of these commands is that candidates that
are directory names are highlighted in buffer `*Completions*'
using face `icicle-special-candidate'.

Another feature is that if you use a prefix argument when acting on
an individual file-name candidate then the file is visited in
read-only mode.  The same invocation of `C-x C-f' can thus open
multiple files, some in read-only mode, some not.

(There are also multi-commands '''`icicle-find-file-read-only'''' and
'''`icicle-find-file-abs-read-only'''', unbound
by default, which are the same as `icicle-find-file' and `icicle-find-file-absolute', except that they visit files in ''read-only'' mode.  For `icicle-find-file-read-only', the prefix-argument behavior is flipped: with a prefix argument when you act on a
candidate file it is ''not'' visited read-only.)











[:icicle-visit-marked-file-of-content-recursive]
[:icicle-visit-marked-file-of-content]
[:icicle-find-file-of-content]
[:MatchFileContent]
[:MatchFileNamesAndFileContentToo]
==== Match File Names and File Content Too ====

Starting with Emacs 23, the '''Icicles''' commands that read file names
let you
optionally provide a [[regexp]] pattern to match against file
'''content'''.  In this they are similar to the buffer-switching
multi-command `icicle-buffer'.

Versions of the file-finding commands are also available that do
not let you search file contents.  Their file names contain
'''`-no-search''''.  Prior to Emacs 23, these are all that are
available, so commands such as `icicle-file' are aliased to them.

(For Emacs 23 and later, commands such as `icicle-file' are
actually aliased to commands that let you search content, and
which have '''`-of-content'''' in their name.)

If you provide a pattern to match file content
then all files whose names match the file-name part of your input
are searched for the content pattern.  '''Icicles''' looks only for a single
content-match within each file it tests.  Choosing a candidate file
just visits it normally --- it does not move to that tested match or
to any other content-match position.  Matching is used only to
filter candidate files.

However, if your input includes a content-matching part that
matches, that part is automatically added to the [[Isearch]] regexp
history, `regexp-search-ring', whenever you hit `S-TAB' to
complete your input.  This means that when you visit the file you
''can immediately search for matches'' using `C-M-s' or `C-M-r'.

(You can also work in the other direction, reusing an Isearch
regexp as a content-matching regexp.  See [[Icicles - History Enhancements#InsertPreviousInputs|Using Completion to Insert Previous Inputs: `M-o']].)

Content-searching is obviously much more costly than file-name
matching, so clearly if you can provide some information about the
file name, that improves performance.  IOW, the more you can limit
the number of files to search, the better.

To search file content, the candidate files are visited, that is,
buffers are created for them and searched.  By default, after the
command is finished these buffers are killed, except for those you actually chose as completion candidate(s) and
any that existed prior to invoking the command.

This automatic extra-buffers cleanup is controlled by option
'''`<tt>[[Icicles - Customization and General Tips#icicle-kill-visited-buffers-flag|icicle-kill-visited-buffers-flag]]</tt>''''.  But providing a [[prefix argument]] to '''`icicle-file'''' flips the behavior specified by that
option for the command duration.  (This is not true for the
commands that read absolute file names.  For them, a prefix
argument has a different meaning.)

You can use option '''`<tt>[[Icicles - Customization and General Tips#icicle-file-skip-functions|icicle-file-skip-functions]]</tt>'''' to specify patterns for file names to exclude from content-searching
when you provide a content-matching pattern.  By default, image files and
byte-compiled [[EmacsLisp|Emacs-Lisp]] files are ignored for content-searching.

If your input contains a content-matching part then, by default,
it is ignored for completion of a directory-name candidate.  The
behavior is governed by options `find-file-run-dired' and
'''`<tt>[[Icicles - Customization and General Tips#icicle-file-search-dir-as-dired-flag|icicle-file-search-dir-as-dired-flag]]</tt>''''.  If both of these options
are non-`nil' then the directory is visited in [[Dired]] mode during
completion, and the Dired listing is searched as the content.

In a [[Dired]] buffer, there are related content-matching
multi-commands that you can use to visit marked files and
subdirectories whose content matches a [[regexp]].

* `icicle-visit-marked-file-of-content', bound to `C-S-f', aka '''`C-F'''', and `C-M-S-f', aka '''`C-M-F'''', for other-window

* `icicle-visit-marked-file-of-content-recursive', bound to '''`##M-+ C-F##'''', and '''`##M-+ C-M-F##'''' for other-window

The latter visit not only the files that are marked in the current
directory, but also those that are ''marked in any marked
subdirectories, and sub-subdirectories etc., '''recursively'''''.  They
are available only if you also use library '''[[Dired+]]'''.

File content-matching is available for all '''Icicles''' commands that
read file names, including '''`icicle-recent-file'''',
'''`icicle-locate-file'''', and '''`icicle-locate''''.

Using a negative [[prefix argument]] when you invoke `icicle-file' (`C-x C-f'), or
any prefix argument when you invoke a command that reads absolute
file names, means that the completion candidates have up to three
parts: the file name, followed by the last modification date,
followed by the file content.

For example, these each match files with names matching `ici',
last modification dates matching `2013', and contents matching
`define-file':

    C-- C-x C-f ici C-M-j 2013 C-M-j define-file

    M-x icicle-locate-file ici C-M-j 2013 C-M-j define-file

The parts of your input pattern
that match any of the candidate parts can be empty.  For example, this matches files with any name, whose last modification date matches `2013 07', and whose contents match `recent file':

    C-- C-x C-f C-M-j 2013 07 C-M-j recent file


'''See Also:'''

* [[#VisitRecentFiles|`icicle-recent-file']]
* [[#FindFilesAnywhere|Find Files Anywhere, Without Knowing Where]]
* [[Icicles - Searching Named Containers]]











[:CyclingIntoSubdirectories]
==== Cycling into Subdirectories ====

The '''Icicles''' commands that use `read-file-name' to read a file or
directory name visit the files or directories you choose.  If you
act on a directory-name completion candidate (e.g. using `RET' or
`C-RET') it is visited using [[Dired]].  And cycling moves past a
directory candidate to the next candidate, the name of a sibling
file or directory.

But sometimes you want not to visit a candidate directory but to
descend into it, to access its own files or subdirectories using
completion.  To do that, you can do either of the following to
expand a directory candidate:

* `C-M-/'
* `C-e TAB' (or `C-e S-TAB')

If you prefer, you can have '''Icicles''' cycle into subdirectories
whenever you choose them using `RET' (or `mouse-2' in
`*Completions*'), by setting [[option]] '''`<tt>[[Icicles - Customization and General Tips#icicle-find-file-expand-directory-flag|icicle-find-file-expand-directory-flag]]</tt>''' to non-`nil'.

The effect
of `RET' and `C-RET' is then the same as `C-M-/' --- directory
candidates are not visited using Dired.  This behavior does not
occur for [[multi-command]] candidate actions such as `C-RET',
`C-mouse-2', and `C-down' --- those continue to open Dired on the
candidate directory.

You can toggle this option using `C-x /'.










[:VisitRecentFiles]
[:VisitFilesForEmacsTags]
==== Visit Recent Files or Files for Emacs Tags ====

You can use '''`icicle-recent-file'''' to open any file that you have
visited recently, perhaps in a previous Emacs session.

Because '''Icicles''' lets you easily sort and filter candidates,
consider customizing [[option]] `recentf-max-saved-items' to a large
number, such as 1000.  The default number (20) is very small because it assumes that you will access the candidates using a menu.

Commands '''`icicle-find-file-in-tags-table'''' and
'''`icicle-find-file-in-tags-table-other-window'''' let you visit files
that are listed in the current Emacs [[TagsFile|tags table]].  You can think of these
potential completion candidates as all of the files in a ''project
defined by the tags table''.

`icicle-recent-file' and `icicle-find-file-in-tags-table' are like `icicle-find-file-absolute': `completing-read' is used, not
`read-file-name' (file names are treated as just strings), and
(for Emacs 23 and later) you can match both file names and file
contents.










[:icicle-locate]
[:icicle-locate-file]
[:icicle-directory-list]
[:FindFilesAnywhere]
==== Find Files Anywhere, Without Knowing Where ====
You can
use '''`icicle-locate'''' or '''`icicle-locate-file'''' to ''find a file when you do not know precisely what
directory'' it is in.  The former requires
GNU/Linux or UNIX command `locate', to work.  The latter does not
require any external program.

Because it takes advantage of `locate' having indexed files on your
file system, `icicle-locate' can be much faster than
`icicle-locate-file'.  Otherwise, these two '''Icicles''' commands work
similarly.

`icicle-locate' and `icicle-locate-file' are like
`icicle-find-file-absolute': file names are absolute, and (for
Emacs 23 and later) you can match both file names and ''file
contents''.  Of course, since these commands work with all of the
files in and under a given directory, this can mean many, many
files, so generally you will want to use an input pattern that
also matches file names.

Since it does not use an index, `icicle-locate-file' looks throughout a given directory,
including throughout all of its subdirectories.  Command '''`icicle-locate-file-no-symlinks'''' is the same, except that
it does not follow symbolic links.  Both of these commands
respect [[option]] '''`<tt>[[Icicles - Customization and General Tips#icicle-ignored-directories|icicle-ignored-directories]]</tt>'''', which is a list of
directories to ignore -- by default, version-control directories.

By default, the target directory for `icicle-locate-file' is the
current directory, but if you supply a non-negative [[numeric prefix argument]] (non-positive means include the date), then you are
prompted for the directory to search.  

If you use a plain prefix argument (`C-u') or a double plain prefix argument (`C-u C-u') then you are prompted to choose a set of directories to use.
This choosing uses [[multi-command]] `icicle-directory-list'.  '''Icicles'''
searches for file-name matches under each of the directories you
choose.  For `C-u C-u', the candidate [[multi-completion]]s 
include the last file-modification date.

In addition, if you turn on the use of [[proxy candidate]]s ('''`##C-M-_##''''),
`icicle-directory-list' also offers proxy candidates that are
[[variable]]s, such as `load-path', whose values are lists that
include directories.  Choosing a proxy candidate adds all of its
directories to the set to be searched.

If you use the ''root of your
file system'' as the search directory, then the '''Icicles''' file-locating commands
will match completion candidates ''anywhere in your file system''.

This can be quite useful.  It gives you much of the power of the
Unix `find' command just for completing input.  And with
incremental completion (see [[Icicles - Icompletion]]), you can see
what matches your input as you type.

Obviously, if you use your entire file system as the set of
completion candidates and you use `icicle-locate-file' (because
you do not have available the external program `locate'), then gathering and matching such a large set
of file names can take some time.

On my hard drive, for instance,
there are 36 GB full of files, and it takes about 40 seconds to
gather all of the file names.  In spite of this inconvenience, this functionality can be useful.
And of course searching a shallower directory tree presents less
of a performance penalty -- you pay for what you get.

However, even if you do not have command `locate', there of having your cake and eating it too.
You can gather all of the file names in your file system ''once'', and
save that list of completion candidates to a ''cache file on disk'', as a snapshot.  See [[Icicles - Persistent Completions]] for how to do this.

You can also do a few things to improve performance when using a
command like `icicle-locate-file' that involves a large set of
completion candidates: Turn off [[IcompleteMode|Icomplete mode]], '''Icicles''' [[incremental completion]], and [[Icicles - Sorting Candidates|sorting]].  You can use keys '''`<tt>C-M-#</tt>'''', '''`<tt>C-#</tt>'''', and
'''`##C-,##'''', respectively, to do this.  But because it is likely that
you will want to do these things most, if not all, of the time,
'''Icicles''' ''does this for you automatically'', by default.

[[user option|User options]] '''`<tt>[[Icicles - Customization and General Tips#icicle-icomplete-mode-max-candidates|icicle-icomplete-mode-max-candidates]]</tt>'''' and '''`<tt>[[Icicles - Customization and General Tips#icicle-sorting-max-candidates|icicle-sorting-max-candidates]]</tt>'''' ''automatically turn off'' Icomplete mode and sorting ''when there are more completion candidates'' than
the option values, and then they turn these back on when there are
fewer candidates.  This is the case regardless of the current
command.

In addition, '''Icicles''' [[multi-command]]s that typically have a large
number of candidates turn off Icomplete mode and '''Icicles'''
incremental completion, and do not turn them on again, regardless
of the number of current candidates at any moment.  When this
happens, a message informs you.  Just use `<tt>C-M-#</tt>' and `<tt>C-#</tt>' to
turn these back on.

You can control which commands do this, by adding/removing
properties '''`icicle-turn-off-icomplete-mode'''' and
'''`icicle-turn-off-incremental-completion'''' to/from the command
symbol.  For example, if you do not want `icicle-locate-file' to
turn either of these off then add this to your [[init file]]
(##~/.emacs##):

    (put 'icicle-locate-file 'icicle-turn-off-icomplete-mode nil)
    (put 'icicle-locate-file 'icicle-turn-off-incremental-completion nil)

On the other hand, you can make any command turn one of these off
by putting a non-`nil' value on its symbol.













[:AbsoluteFileNames]
=== Absolute File Names and Different Directories ===

Since `completing-read' has no understanding of file-name syntax,
including remote file-name syntax, `icicle-find-file-absolute'
(`C-u C-x C-f') and similar commands are similarly ignorant.  (You
can nevertheless use '''`##C-.##''' with these '''Icicles''' commands, to toggle respect of `completion-ignored-extensions'.)  In particular, these commands will not let you complete to
a remote file name if the current directory is local.  They also
will not let you complete to a file name in a different local
directory.

Because all '''Icicles''' commands that read file names use [[lax]]
completion, you can nevertheless ''visit'' a file in a different
directory (remote or local) from the current one, even though you
cannot ''complete'' your input to such a name.  That is, you can
always use `RET' with any file name as minibuffer input.

So how can you ''complete'' your input to an ''absolute'' file-name in a
''different directory''?  By retrieving a saved candidate set that has
such absolute names and then completing against that set.  For
example, you can retrieve a set that represents files on a remote
machine and complete to their names even from a local directory.
All that counts for `completing-read' is that your input can match
candidates, where that matching is ordinary (apropos or prefix)
string matching.

To ''create'' such a saved set of names, you can visit the directory
(perhaps remote) that contains the files and then use `C-u C-x C-f' and `##C-}##' to save the candidates.  You can later retrieve
this saved set for completion, no matter what the current
directory is.  As another example, you can use
`icicle-locate-file' in a remote directory to create a saved set
that includes remote files that are all somewhere under that
remote directory.

In addition, you can add more file names to an existing saved set
using `##C->##', `##C-)##', `M-mouse-3', `insert', or `M-S-mouse-2' -- see
[[Icicles - Candidate Sets#SaveMore|Add More Saved Candidates]]. The added names can come
from a different directory than files already in the saved set. In
this way, you can build up a saved set that includes files from
any directories, some of which can be local and some remote, some
remote from one host, some remote from another, and so on. You can
create a saved set with any ''mix of absolute file names from any
locations''.

'''Remember this:'''

* To ''create'' and ''add to'' a saved set of ''absolute'' file names, use a
  command that expects absolute file names, and do this from the
  ''directory that contains the files'' you want to add.

* When you ''retrieve'' a saved set of file-name candidates for
  completion, use a command that expects the same kind of file
  names, relative or absolute, as the saved names.  For example,
  if you save a set of project files that are spread over
  different directories (and hence are absolute), then retrieve
  that candidate set using, say, `C-u C-x C-f' (absolute), not
  `C-x C-f' (relative).


[:C-cC-d]
Finally, although the commands that read absolute file names are
essentially ignorant of directory hierarchies and of file names as
such, so that they treat their candidates only as simple strings,
most of these commands nevertheless define their domain of
possible file-name candidates relative to some starting directory.

This is the case for ''all'' commands that read absolute file names,
except for the `icicle-locate*' family.  You can use '''`C-c C-d'''' (think UNIX command `cd') during completion to
change the current working directory (`default-directory') on the
fly.  You are prompted for the directory.  The domain of possible
candidates is recomputed relative to the new `default-directory'.

Use `C-c C-d' this way as many times as you like.  You can use
this feature to add file names from different directories to a
saved set of candidates.  When the command is finished, the
original `default-directory' is restored.


'''See also:'''

* [[Icicles - Persistent Completions]] for information about saving a set of file names persistently

* [[Icicles - Candidate Sets]] for information about creating, saving, and retrieving sets of file names

* [[Icicles - Large Candidate Sets]] for ways to deal with a large number of candidates

* LocateFilesAnywhere for other, non-persistent ways to locate files.

* [[IciclesUserDefinedCommands#icicle-locate|icicle-locate]] for an '''Icicles''' multi-command that acts as a wrapper for the GNU/Linux or Unix `locate' program.

* [[Icicles - Multi-Completions]] for information about using multi-completions.

* [[Icicles - Support for Projects#TagsFileProject|Icicles - Tags File Projects]] for more about `icicle-find-file-in-tags-table'

* [[Icicles - Completion On Demand]] for information about on-demand insertion of file names, using completion, from any minibuffer

* [[Icicles - Nutshell View#MultiCompletion|Match Multiple Things Together]] about content-searching

* [[Icicles - Buffer-Name Input]] about visiting recently used files or
files whose names have been cached, and about content-searching
them

* [[Icicles - Bookmark Enhancements#TaggingFiles|Tagging Files]] for more information about tagging files







----


|| *Previous:*  [[Icicles - Buffer-Name Input]] || '''[[Icicles]]''' || IciclesIndex || *Next:* [[Icicles -  Persistent Completions]] ||



DrewsElispLibraries referenced here: Lisp:icicles.el

CategoryCommands 
CategoryCompletion
CategoryRegexp
CategoryDirectories
CategoryFiles
CategoryProgrammerUtils
CategoryCode