Commandline reference

You can control LocalSearch using the localsearch3 commandline tool. The various subcommands are documented below.

This documentation is also available on your computer using the man command.

localsearch-3

Name

localsearch-3 — Used to crawl the file system to mine data.

Synopsis

localsearch-3 [OPTION…]

DESCRIPTION

localsearch-3 is not supposed to be run by the user since it is started by its .desktop file when the user logs in. It can also be started manually of course for debugging purposes. You can not run more than one instance of this at the same time.

localsearch-3 mines information about applications and files only.

OPTIONS

-?, --help
Show summary of options.
-V, --version
Returns the version of this binary.
-s, --initial-sleep=SECONDS
Sets the initial sleep time before crawling the file system is started. If the --no-daemon option is used, this option is ignored.
-n, --no-daemon
Tells the miner to exit once all indexing has finished and the database is up to date. This is not the default mode of operation for the miner, usually it stays around acting like a daemon to monitor file updates which may occur over time. This option renders the --initial-sleep option moot.
-e, --eligible=FILE
Checks if FILE is eligible for being mined based on the current configuration rules. In addition to this, it will check if FILE would be monitored for changes. This works with non-existing FILE arguments as well as existing FILE arguments.

ENVIRONMENT

G_MESSAGES_DEBUG
Controls verbose log output from GLib-based code. Use G_MESSAGES_DEBUG=Tracker to see only Tracker-related logs, or G_MESSAGES_DEBUG=all to see everything.
TRACKER_DEBUG

Enables more specialized debug output. Pass a comma-separated list of one or more keywords:

config
miner configuration
miner-fs-events
internal processing of localsearch-3
monitors
change events from filesystem monitors
statistics
show statistics about how many files were processed
status
log the status messages that are published over D-Bus

SEE ALSO

localsearch3-info(1).


localsearch-daemon

Name

localsearch-daemon — Start, stop, restart and list daemons responsible for indexing content

Synopsis

localsearch daemon [options...]
localsearch daemon -s | -t [daemons] | -k [daemons] | -l
localsearch daemon -f | -w [ontology]
localsearch daemon --miner <miner> --pause[-for-process] <reason>
localsearch daemon --miner <miner> --resume <cookie>

DESCRIPTION

Tracker indexes content with daemon processes that run in the background. The localsearch daemon command allows for control of these components. This ranges from starting, stopping and killing processes to pausing and resuming them.

In addition to all this, there are ways to follow or watch what is happening in real time from a top level and right down where the SPARQL commits are happening too.

If no arguments are provided this command will show the current status of all Tracker data miners.

The data miners can be paused or resumed using this command and you can also list miners running and available.

OPTIONS

-p, --list-processes
This lists all Tracker processes in the system.
*-k, --kill
This uses SIGKILL to stop all Tracker processes found matching the parameter, if no extra parameter is passed, "all" will be assumed. This is not advised unless you are having problems stopping Tracker in the first place. This GUARANTEES death.
*-t, --terminate=
This uses SIGTERM to stop all Tracker processes. This is recommended over --kill because it gives the processes time to shutdown cleanly.
-s, --start
Starts all miners.
-f, --follow
Follow status changes to daemons as they happen. This is a top level view of what is happening. You will see the name for each daemon and a state with the progress in that state.

This requires Ctrl+C to stop and return to the command line. Each new status is put on a new line.

-w, --watch=[ontology]
Watch changes that happen to the database in real time. This requires Ctrl+C to stop and return to the command line.

If ontology is unspecified, all updates are shown. The ontology can be a comma separated list of shorthand or long hand ontology properties. For example:

    $ localsearch daemon -w nie:url,nie:mimeType,nfo:fileSize,nie:dataSource
    Now listening for resource updates to the database
    All nie:plainTextContent properties are omitted

    Press Ctrl+C to stop

    'nfo:Document'
       'nfo:fileSize' = '1770'
       'nie:dataSource' = 'http://tracker.api.gnome.org/ontology/v3/tracker#extractor-data-source'
       'nie:mimeType' = 'text/plain'
       'nie:url' = 'file:///home/martyn/.bash_aliases'
    'nfo:Document'
       'nie:dataSource' = 'http://tracker.api.gnome.org/ontology/v3/tracker#extractor-data-source'

    ...
--list-common-statuses
This will list statuses most commonly produced by miners and the store. These statuses are not translated when sent over D-Bus and should be translated by each application. These are not considered static and are subject to change at any point.

Additionally, these statuses are not the only ones which may be reported by a miner. There may be other states pertaining to the specific roles of the miner in question.

--list-miners-running
This will list all miners which have responded to a D-Bus call. Sometimes it is helpful to use this command with --list-miners-available.
--list-miners-available
This will list all miners which are available even if they are not running at the moment.
--pause-details
For listing all miners which are paused and the reasons for being paused, you can use this. It will also display the application that requested the pause too.
--miner=<miner>
This argument is used with --pause or --resume to say which miner you want to pause or resume. You can use the full D-Bus name, e.g. "org.freedesktop.Tracker3.Miner.Files" OR you can use the suffix, e.g. "Files".
--pause=<reason>
The reason here is useful to know WHY the miner should be paused. A miner can be paused many times by multiple applications. Only when all pauses have been resumed will it continue. If successful, a cookie will be given to uniquely identify the request. This cookie is used to resume the pause at a later stage.
--pause-for-process=<reason>
This works exactly the same way as --pause with the exception that it only keeps the pause active while the calling process is alive. As soon as you press Ctrl+C the pause is resumed automatically.
--resume=<cookie>
The cookie is given by a successful --pause command. It is a number which identifies each pause request. When all pauses have been resumed, the miner will resume working.

localsearch-extract

Name

localsearch-extract — Extract metadata from a file.

SYNOPSYS

localsearch extract FILE

DESCRIPTION

localsearch extract reads the file provided and extracts any metadata it can from this file, then displays the metadata on standard output.

The metadata is displayed as a SPARQL update command, that can be run against a SPARQL endpoint to update its copy of the metadata.

The actual extraction is done by a separate process. This is done to isolate the calling process from any memory leaks or crashes in the libraries Tracker uses to extract metadata.

For more information see the libtracker-extract reference documentation.

OPTIONS

-o, --output-format=<FORMAT>
Choose which format to use to output results. Supported formats are sparql, turtle and json-ld.

EXAMPLES

Using command line to extract metadata from a file
$ localsearch extract /path/to/some/file.mp3

ENVIRONMENT

G_MESSAGES_DEBUG
Controls verbose log output from GLib-based code. Use G_MESSAGES_DEBUG=Tracker to see only Tracker-related logs, or G_MESSAGES_DEBUG=all to see everything.
TRACKER_DEBUG

Enables more specialized debug output. Pass a comma-separated list of one or more keywords:

config
extractor configuration
statistics
show statistics about how many files were processed
status
log the status messages that are published over D-Bus

SEE ALSO

localsearch status(1), localsearch info(1).


localsearch-index

Name

localsearch-index — Index content using the Tracker filesystem miner

Synopsis

localsearch index
localsearch index --add [--recursive] <dir> [[dir] ...]
localsearch index --remove <path> [[dir] ...]

DESCRIPTION

This command causes the Tracker filesystem miner to process the given directories. These changes are persistent across future restarts.

If invoked without arguments, the currently indexed locations will be listed.

SEE ALSO

localsearch-3(1).


localsearch-info

Name

localsearch-info — Retrieve all information available for a certain file.

Synopsis

localsearch info [options…] <file1> [[file2] …]

DESCRIPTION

localsearch info asks for all the known metadata available for the given file.

Multiple file arguments can be provided to retrieve information about multiple files.

The file argument can be either a local path or a URI. It also does not have to be an absolute path.

OPTIONS

-f, --full-namespaces
By default, all keys and values reported about any given file are returned in shortened form, for example, nie:title is shown instead of http://tracker.api.gnome.org/ontology/v3/nie#title. This makes things much easier to see generally and the output is less cluttered. This option reverses that so FULL namespaces are shown instead.
-c, --plain-text-content
If the resource being displayed has nie:PlainTextContent (i.e. information about the content of the resource, which could be the contents of a file on the disk), then this option displays that in the output.
-i, --resource-is-iri
In most cases, the file argument supplied points to a URL or PATH which is queried for according to the resource associated with it by nie:url. However, in cases where the file specified turns out to be the actual URN itself, this argument is required to tell "localsearch info" not to do the extra step of looking up the URN related by nie:url.

For example, consider that you store URNs by the actual URL itself and use the unique nie:url in another resource (which is quite reasonable when using containers and multi-resource conditions), you would need this argument to tell "localsearch info" that the file supplied is actually a URN not URL.

-t, --turtle
Output results as Turtle RDF. If -f is enabled, full URIs are shown for subjects, predicates and objects; otherwise, shortened URIs are used, and all the prefixes Tracker knows about are printed at the top of the output.

SEE ALSO

tinysparql sparql(1).

http://nepomuk.semanticdesktop.org/ http://www.w3.org/TR/rdf-sparql-query/


localsearch-reset

Name

localsearch-reset — Reset the index and configuration

Synopsis

localsearch reset [--filesystem | --rss] [--file FILE]

DESCRIPTION

The reset command will change either your configuration or index irreversibly and should be used with care. Other than tags, actual data (e.g. files) should not be affected by this command.

The "index" is a link between your content (either locally or remotely) and how it can be found quickly using a number of different queries. Under the hood, this is done using a database.

Removing all data and starting again from the beginning with an empty data set (which is a common use of this command) is done by using the hard reset option. This behaves as if Tracker was just installed.

OPTIONS

-s, --filesystem
Removes data stored by tracker-miner-fs(1). The miner will automatically recreate its cache from the filesystem when it restarts.
-r, --rss
Removes data stored by tracker-miner-rss(1).
-f, --file FILE
Resets all indexed information about FILE, works recursively for directories. Nothing will be done if FILE is not currently indexed. After deletion, a request to reindex this data will be immediately issued.

SEE ALSO

localsearch-daemon(1). localsearch-3(1).


Name

localsearch-search — Search for content by type or across all types

Synopsis

localsearch search [options…] [resource-type] <search-terms>

DESCRIPTION

localsearch search searches all indexed content for the given search terms. Results are returned in ascending order.

<search-terms>

One or more words to search for. When multiple terms are provided, the default operation is a logical AND. For logical OR operations, see -r.

If no search terms are supplied but a resource-type is given (like --folders for example), then ALL items in that category are returned.

Only resources which currently exist will be returned by this command (see --all for more information).

RESOURCE TYPES

-f, --files
Search for files of any type matching search-terms.
-s, --folders
Search for folders matching search-terms.
-m, --music
Search for music files matching search-terms.
--music-albums
Search for music albums matching search-terms.
--music-artists
Search for music artists matching search-terms.
-i, --images
Search for images matching search-terms.
-v, --videos
Search for videos matching search-terms.
-t, --documents
Search for documents matching search-terms.
--software
Search for software installed matching search-terms. Returns a list of desktop files and application titles found.
--software-categories
Search for software categories matching search-terms. Returns a list of urns and their categories (e.g. Settings, Video, Utility, etc).
--feeds
Search through RSS feed information matching search-terms. Returns a list of those found.

OPTIONS

-l, --limit=<limit>
Limit search to limit results. The default is 10 or 512 with --disable-snippets.
-o, --offset=<offset>
Offset the search results by offset. For example, start at item number 10 in the results. The default is 0.
-r, --or-operator
Use OR for search terms instead of AND (the default)
-d, --detailed
Show the unique URN associated with each search result. This does not apply to --music-albums and --music-artists.
-a, --all
Show results which might not be available. This might bebecause a removable media is not mounted for example. Without this option, resources are only shown if they exist. This option applies to all resource types except for --music-artists, --software, --software-categories and --feeds.
--disable-snippets
Results are shown with snippets. Snippets are context around the word that was searched for in the first place. This gives some idea of if the resource found is the right one. Snippets require Full Text Search to be compile time enabled AND to not be disabled with --disable-fts. Using --disable-snippets only shows the resources which matched, no context is provided about where the match occurred.
--disable-fts
If Full Text Search (FTS) is available, this option allows it to be disabled for one off searches. This returns results slightly using particular properties to match the search terms (like "nie:title") instead of looking for the search terms amongst ALL properties. It is more limiting to do this, but sometimes searching without FTS can yield better results if the FTS ranking is off.
--disable-color
This disables any ANSI color use on the command line. By default this is enabled to make it easier to see results.

SEE ALSO

localsearch status(1), localsearch tag(1), localsearch info(1).


localsearch-status

Name

localsearch-status — Provide status and statistics on the data indexed

Synopsis

localsearch status
localsearch status [[expression1]...]
localsearch status --stat [-a] [[expression1]...]

DESCRIPTION

Display the status of the current index and data set. A summary of recorded failures during file metadata indexing is also displayed.

Providing a search expression will list the full details of the recorded failures matching the filename.

With the --stat option, displays statistics about the RDF classes and how many of each exist for data set that has been indexed. For example, "10 Folders".

OPTIONS

--stat[=expression]
By default, only common and useful classes are shown, e.g. "nfo:Document" or "nfo:Folder", for a full set of statistics, see the --all option.

If one or more expression arguments is given, the statistics returned are filtered to only show information those RDF types matching expression (case folded and matching accented variants). The RDF classes are detailed by the Nepomuk otology specification. A list of possible classes matching expression, see localsearch sparql -c.

-a, --all
Display statistics about ALL RDF classes that exist in the database. Without this option only the common RDF classes will be shown, for example "nfo:Document" and "nfo:FileDataObject".

This option is implied if search terms are provided to filter ALL possible statistics.

SEE ALSO

localsearch daemon(1), localsearch info(1).

  • http://nepomuk.semanticdesktop.org/
  • http://www.w3.org/TR/rdf-sparql-query/

localsearch-tag

Name

localsearch-tag — Add, remove and list tags.

Synopsis

localsearch tag FILE1 [FILE2 ...] [-l <limit>] [-o <offset>] [-r]
localsearch tag -t [[TAG1] [TAG2] ...] [-s] [-r]
localsearch tag -a <TAG> [-e <description>]
localsearch tag -d <TAG>

DESCRIPTION

List tags for local files or by the tag labels themselves if -t is used.

It’s also possible to manage tags with the -a and and -d options.

The FILE argument can be either a local path or a URI. It also does not have to be an absolute path.

OPTIONS

-t, --list
List all tags. Results include the number of files associated with that tag and the tag’s unique identifier. You can show the files associated with each tag by using --show-files.

The TAG arguments are optional. If no TAG argument is specified, all tags are listed. If one or more TAGs are given, either matching tags are listed (OR condition). For example, this will match any tags named either foo, bar or baz:

$ localsearch tag -t foo bar baz
-s, --show-files
Show the files associated with each tag. This option is ONLY available WITH the --list option.
-a, --add=TAG
Add a tag with the name TAG. If no FILE arguments are specified, the tag is simply created (if it didn’talready exist) and no files are associated with it. Multiple FILE arguments can be specified.
-d, --delete=TAG
Delete a tag with the name TAG. If no FILE arguments are specified, the tag is deleted for ALL files. If FILE arguments are specified, only those files have the TAG deleted.
-e, --description=STRING
This option ONLY applies when using --add and provides a description to go with the tag label according to STRING.
-l, --limit=N
Limit search to N results. The default is 512.
-o, --offset=N
Offset the search results by N. For example, start at item number 10 in the results. The default is 0.
-n, --and-operator
Use AND operator for search terms instead of OR (the default). For example:
$ localsearch tag -s -t sliff sloff

Should show files in the database that have both the sliff and sloff tags.

SEE ALSO

localsearch search(1), localsearch info(1).


localsearch-writeback-3

Name

localsearch-writeback-3 — Used to write metadata set in Tracker back to physical files.

Synopsis

localsearch-writeback [OPTION…]

DESCRIPTION

localsearch-writeback is not supposed to be run by the user since it is started by its .desktop file when the user logs in. It can also be started manually of course for debugging purposes. You can not run more than one instance of this at the same time.

localsearch-writeback writes metadata from the Tracker database back into files only. Currently support is limited to XMP metadata (which covers PNG, JPEG, TIFF, MP4 and 3GPP formats), play lists (which covers MPEGURL, SCPLS and IRIVER formats) and taglib supported mime types (which covers MP3, MP4, OGG, WAV, FLAC and some Windows media formats).

OPTIONS

-?, --help
Show summary of options.
-V, --version
Returns the version of this binary.
-d, --disable-shutdown
Disable shutting down after 30 seconds of inactivity.

SEE ALSO

localsearch-3(1). localsearch-extract(1).