Commandline reference¶
You can control Tracker Miners using the tracker3 commandline tool. The various
subcommands are documented below.
This documentation is also available on your computer using the man command.
tracker3 daemon¶
Name
tracker3-daemon — Start, stop, restart and list daemons responsible for indexing content
Synopsis
tracker3 daemon [options...] tracker3 daemon -s | -t [daemons] | -k [daemons] | -l tracker3 daemon -f | -w [ontology] tracker3 daemon --miner <miner> --pause[-for-process] <reason> tracker3 daemon --miner <miner> --resume <cookie>
DESCRIPTION
Tracker indexes content with daemon processes that run in the background. The tracker3 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:
$ tracker3 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.
tracker3 extract¶
Name
tracker3-extract — Extract metadata from a file.
DESCRIPTION
tracker3 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
- $ tracker3 extract /path/to/some/file.mp3
ENVIRONMENT
- G_MESSAGES_DEBUG
-
Controls verbose log output from GLib-based code. Use
G_MESSAGES_DEBUG=Trackerto see only Tracker-related logs, orG_MESSAGES_DEBUG=allto 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
tracker3 index¶
Name
tracker3-index — Index content using the Tracker filesystem miner
Synopsis
tracker3 index tracker3 index --add [--recursive] <dir> [[dir] ...] tracker3 index --remove <path> [[dir] ...]
tracker3 info¶
Name
tracker3-info — Retrieve all information available for a certain file.
DESCRIPTION
tracker3 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 "tracker3 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 "tracker3 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.
tracker3 reset¶
Name
tracker3-reset — Reset the index and configuration
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.
tracker3 search¶
Name
tracker3-search — Search for content by type or across all types
DESCRIPTION
tracker3 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-categoriesand--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.
tracker3 status¶
Name
tracker3-status — Provide status and statistics on the data indexed
Synopsis
tracker3 status tracker3 status [[expression1]...] tracker3 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 tracker3 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.
tracker3 tag¶
Name
tracker3-tag — Add, remove and list tags.
Synopsis
tracker3 tag FILE1 [FILE2 ...] [-l <limit>] [-o <offset>] [-r] tracker3 tag -t [[TAG1] [TAG2] ...] [-s] [-r] tracker3 tag -a <TAG> [-e <description>] tracker3 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:
$ tracker3-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:
$ tracker3-tag -s -t sliff sloff
Should show files in the database that have both the sliff and sloff tags.