METAINDEXMANAGER()

NAME
metaindexmanager - extendable metaindex file manager

SYNOPSIS

metaindexmanager [-h] [-m metaindex config file] [-l loglevel] [--log-file logfile] [--select-file-mode] [--select-file-output file] [location ...]

DESCRIPTION

metaindexmanager is a text user interface (TUI) file manager that allows you to browse and manipulate your documents and files by their metadata tags.

You can also use metaindexmanager from other applications to select files. See below in Select file mode.

OPTIONS

The general parameters are:

-h  Show the help and exit.

-m metaindex config file
    Location of your metaindex config file. If not specified, the default location is used. Usually that’s ~/.config/metaindex.conf.

-l loglevel
    The the level of details shown in the log file. Your options are fatal, error, warning, info, and debug. Defaults to warning.

--log-file logfile
    Where to write the log to. Defaults to ~/.local/share/metaindexmenager/ui.log

    Very useful if the application crashes or shows errors in the status line.

--select-file-mode
    Run in select file mode. See below in Select file mode for details.

    Not used by default.

--select-file-output file
    What file to write the selected file(s) to. See Select file mode for details on how to use this.

    Defaults to - (standard output).

location
    Provide any locations or search queries to open on startup.

    If the location you provide is a path to a folder, it will open a file panel. Otherwise the location is interpreted as a search query and a metadata panel is opened with that search query.

    This, for example, will open two panels. One in your home folder and one showing all indexed files that are images:

    metaindexmanager ~ "mimetype:image"

SHORTCUTS

The following default shortcuts are available in the various panels.

  General

These shortcuts work in every panel:

•   q, close the current panel

•   X, quit metaindexmanager

•   :, enter a command

•   Tab, next panel

•   gt, next panel

•   gT, previous panel

•   gp, go to panel by number

•   gnf, new file browser panel

•   gnd, new document browser panel

•   y0, clear clipboard

•   zs, use the horizontal split layout

•   zt, use the tabbed layout

•   ^L, repaint

•   ', jump to mark

•   arrow down, next item

•   arrow up, previous item

•   page down, next page

•   page up, previous page

•   home, go to start

•   end, go to end

    These shortcuts only work in the file browser:

•   R, refresh

•   arrow right, open the file in an external viewer or enter the folder

•   arrow left, go up in the folder hierarchy

•   zh, toggle display of hidden files

•   gh, go to your home folder

•   gd, show the metadata details for the selected item

•   e, edit metadata of the selected item

•   E, edit metadata with an external text editor

•   !, run a shell command or open a shell

•   cd, change directory

•   dD, delete the selected item (experimental)

•   yy, copy the selected path to clipboard

•   ya, append the selected path to clipboard

•   m, mark the selected item for quick access

•   space, select the item

•   uv, clear selection

•   v, invert selection

    These shortcuts only work in the document browser:

•   R, refresh

•   arrow right, open the selected item in an external viewer

•   /, enter a new search term

•   F3, enter a new search term

•   gs, enter a new search term

•   gl, open currently selected item in new file browser

•   gd, open the metadata viewer for the selected item

•   yy, copy the path of the selected item to clipboard

•   ya, append the path of the selected item to clipboard

•   m, mark the selected item for quick access

•   e, edit metadata of the selected item

•   E, edit metadata with an external text editor

    These shortcuts only work in the metadata editor:

•   arrow right, open the file in an external viewer

•   gl, open currently selected item in new file browser

•   E, edit metadata with an external text editor

•   return, edit the selected metadata tag

•   i, edit the selected metadata tag

•   o, add a new value with the same tag

•   c, clear the selected metadata tag value and start editing

•   a, add a new tag

•   dd, delete the selected tag

•   u, undo the most recent change

•   U, undo all changes

•   r, redo change

•   ^R, redo change

•   yy, copy tag to clipboard

•   ya, append tag to clipboard

•   pp, paste tag from clipboard

•   pP, paste tag from clipboard

FILES

The configuration file of metaindexmanager is by default expected at ~/.config/metaindexmanager/config.rc and consists of one command per line (usually bind and set commands, see Commands below). Empty or commented lines (starting with a #) are ignored.

Python files in ~/.local/share/metaindexmanager/addons/ are considered addons and will be loaded upon startup. See Addons below for details.

metaindexmanager will create a logfile to report unexpected or erroneous behaviour. The location of that logfile can be manually configured by providing the --log-file parameter upon startup. The default location is ~/.local/share/metaindexmanager/ui.log.

SELECT FILE MODE

You can run metaindexmanager in --select-file-mode to use it as an "open file dialog" in various applications, like (neo)mutt.

When running in select file mode, the <Return> key will be used to select the current file, exit the program and write the full path to the selected file into --select-file-output (by default the standard output).

To select any indexed text file or something from your home folder you could run this:

metaindexmanager --select-file-mode "mimetype:plain/text" "~"

In actual use cases, you will likely have to write the result to a file with the --select-file-output=file parameter.

  Example use case: (neo)mutt

If you wanted to use this in (neo)mutt to select email attachments, you could use the script file mtattach.sh (in extras) and set it up in mutt with this macro:

# example (neo)mutt configuration to use 'a' in the mail composition
# screen to attach a file using metaindexmanager select file mode
macro  compose  a  "<shell-escape>mtattach.sh<return><enter-command>source /run/user/`id -u`/mtattach.rc<return><shell-escape>rm /run/user/`id -u`/mtattach.rc<return>" "Attach file"

The mtattach.sh script launches metaindexmanager with the --select-file--mode and writes the selected file name into /run/user/`id -u`/mtattach.rc. (neo)mutt will then read that file as a command to execute the attaching.

ADDONS

Beware that addons are just python files. They can in theory do anything on your computer with your permissions. If you install a malicious addon, it could upload all your files to the internet and/or encrypt all your files and ask you for ransom.

Never install addons from untrusted sources!

  Installing

To install an addon, copy the corresponding .py file into your addons folder (usually at ~/.local/share/metaindexmanager/addons/).

  Writing your own

Currently there are two possible type of addons:

•   commands, extending metaindexmanager.command.Command, and

•   layouts, extending metaindexmanager.layouts.Layout

    Be sure to add the @registered_command or @registered_layout decorators to your classes.

    Have a look at the layouts in metaindexmanager.layouts and the commands in metaindexmanager.commands to understand how commands work. metaindexmanager.docpanel and metaindexmanager.filepanel also have a bunch of commands defined that are restricted to these panels.

CONFIGURATION OPTIONS

Configuration options can be set using the set command. Either during runtime from the command line or in the configuration file.

The following options exist:

all.editor
    What text editor to use when a text editor should be launched from within metaindexmanager.

files.use-icons
    Set this to yes (or 1, y, on) to use icons in the file and folder listing. That means that the shell variables USERDIR_ICONS and LS_ICONS will be used to find out what icon to show per entry.

    The format of LS_ICONS and USERDIR_ICONS is based on LS_COLORS: a : separated list of filetype/folder names assigned to font awesome/nerdfont icons. For example, if you want to use a special icon for your downloads and music folders, you could set your USERDIR_ICONS variable to downloads=:music=. Similarly, to show all normal files as f, folders as F and only JPEG files as , you could set your LS_ICONS variable to fi=f:di=F:*.jpeg=:*.jpg=.

    metaindexmanager has some defaults built-in.

documents.columns
    Defines the default columns for any new documents panel.

    Columns are metadata tag names, like extra.title or mimetype. You may also use synonyms (author instead of only extra.author). To show more than just the first value (in case a document has multiple values for one metadata tag), you can add a + after the tag name.

    The special column icon is not a metadata tag, but instead shows an icon (see files.use-icons option above) based on the file type.

    The default is title filename tags+ mimetype.

editor.multiline-indicator
    What single character to show when a metadata tag has line breaks.

    Defaults to ….

editor.cutoff-indicator
    What single character to show when a metadata tag is longer than can be shown with the screen size.

    Defaults to →.

COMMANDS

Commands can be bound to shortcuts or entered directly in the command line. The command to open the command line is called enter-command and usually bound to :.

Based on what panel is currently in focus (file browser, document browser, editor, etc.) different commands may be available. The autocompletion in the command line should be aware of that and provide only valid suggestions.

Some commands accept or even require additional parameters that can be given on the commandline, but are a bit more tricky when bound to shortcuts. See details for that below in the bind command.

Here is a list of all commands:

close
    Closes the currently focused panel. Once the last panel is closed, metaindexmanager will end.

quit
    Quit metaindexmanager.

next-panel
    Focus the next panel.

previous-panel
    Focus the previous panel.

focus
    Focus the given panel. If called with a parameter, e.g. focus 2, it will focus panel with label 2. If called without a parameter, it will ask the user for the panel to focus on.

new-file-panel
    Open a new file browser panel.

new-documents-panel
    Open a new document browser panel.

enter-command
    Open the command line so the user can enter commands.

cancel-command
    Close the command line and return focus to the previous panel.

repaint
    Enforce a repaint of the screen.

layout
    Change the layout of the panels. Provide the name of the layout you want to use as the first parameter. If you don't give a parameter, the available layouts will be listed for you.

source
    Load the configuration file given in the first parameter to this command. Usually only used from your configuration file.

bind
    Bind a command to a shortcut. Expects three parameters: scope, key(s), and command.

    The scope is either any (meaning any panel; file browser, document browser, metadata editor, etc.) or either of documents (a document browser panel), files (a file browser panel), editor (a metadata editor panel).

    Keys can be single keys, like c or C (to indicate the use of the shift key), ^H (to indicate the use of a control key), or special key names like <return> or <escape>. Keys can also be sequences of keys, like gTx<backspace>^Y to indicate the the user must do this magic dance on the keyboard in sequence to call the bound command.

    Commands can be given in three different ways. The basic case is to just give a command name, like enter-command. This command does not expect any parameters, to nothing more is required. If a command expects parameters, you can provide them right in this parameter, but you must prefix the command with ::, for example to bind a shortcut to switch to the tabbed layout, you could write bind any LT "::layout tabbed". The third possibility is to only open the command line, type the first part of the command and let the user input the rest, like this: bind any L? :layout.

    An optional last parameter may be used to give a command a nice help text.

set Set a configuration option. Expects two parameters: configuration option name and value. If only the configuration name is given, the current value is shown. The configuration option name is scope.name, with scope either being all (meaning, generic application level configuration) or either of the panel scopes (documents, files, editor, etc.).

    Example: set all.opener xdg-open

    For available configuration options, see above in Configuration options

details
    Open the metadata viewer to show all metadata for the currently selected file.

    Only available in document browser and file browser.

edit-metadata
    Edit the metadata of the currently selected file.

    Only available in document browser, metadata viewer, and file browser.

edit-metadata-external
    Edit the metadata of the selected item in an external text editor. If you set the configuration option all.editor, this text editor will be used. Otherwise the environment variables VISUAL and EDITOR are checked in that order to find an existing program.

    Only available in document browser, metadata editor, and file browser.

open
    Open the selected item in the currently selected panel. This will usually open the file in an external program or, if a folder is selected, navigate to that folder.

    Only available in document browser, metadata editor, and file browser.

select-and-exit
    If started in --select-file-mode this command can be called to quit metaindexmanager and have the currently selected item be the file to use (for whatever purpose you called metaindexmanager with that option).

    Only available in document browser and file browser.

copy
    Copy the path of the currently selected item to the metaindexmanager internal clipboard. This command accepts a parameter to identify the clipboard that you want to copy the path into. If no parameter is provided, the default clipboard is used.

    Only available in document browser and file browser.

append
    Append the path of the currently selected item to the metaindexmanager internal clipboard. This command accepts a parameter to identift the clipboard that you want to use. See copy for more details on clipboard naming.

    Only available in document browser and file browser.

clear-clipboard
    Clear the named clipboard (identified by the first parameter), or clear the default clipboard. See copy for more details on clipboards.

refresh
    Refresh the current panel. This means reloading the content, not just redrawing.

    Only available in document browser and file browser.

mark
    Bookmark the currently selected item. If no parameter is given, the user will be asked to provide an identifier for that bookmark (single ASCII letters only). Otherwise the parameter will be used as the identifier.

    Only available in document browser and file browser.

ocr Run optical character recognition on the selected item. This requires that OCR is configured.

    Only available in document browser, file browser, and metadata editor.

index
    Run the indexer on the selected item. If a folder is selected, the indexer is run in recursive mode, indexing everything in the folder and the subfolders.

    Only available in document browser, file browser, and metadata editor.

jump-to-mark
    Jump to the bookmark identified by the first parameter to this command. If no parameter is given, the user will be asked to select from the available bookmarks. If the current panel is suitable to display that bookmark, the bookmark will be opened in it. Otherwise a new panel will open.

    Only available in document browser and file browser.

select
    Toggle the selection of the current item.

    Only available in document browser and file browser.

clear-selection
    Unselect all selected items.

    Only available in document browser and file browser.

invert-selection
    Invert the selection of the currently visible items.

    Only available in document browser and file browser.

go-to-location
    Open the path to the currently selected item in a new file browser panel.

    Only available in document browser, metadata viewer, and metadata editor.

rm  Delete the selected item.

    Only available in the file browser.

mkdir
    Create a new folder here. The first parameter is the name of the folder.

    Only available in the file browser.

cd  Open the path given as the first parameter to this command.

    Only available in the file browser.

shell
    Execute a command in the shell in this folder. Either the command is given as the parameter(s) to shell or a shell is simply being launched at this point, which you will have to exit to return to the metaindexmanager.

toggle-hidden
    Toggle whether or not hidden files should be shown.

    Only available in the file browser.

go-to-parent
    Go up in the file hierarchy.

    Only available in the file browser.

search
    Search your documents using the search term given as the first parameter.

    The search term is passed into metaindex. Please check the syntax of search queries there. You can also find the documentation here: https://github.com/vonshednob/metaindex/blob/main/doc/metaindex.rst#search-query-syntax

    Only available in the document browser.

columns
    Set the visible columns to the parameters. If no parameters are given, the current configuration is shown.

    This commands overrides the default column configuration that is set through set documents.columns (see Configuration options above) for the current panel.

    Only available in the document browser.

edit-mode
    Edit the value of the selected metadata tag.

    Only available in the metadata editor.

edit-multiline
    Edit this metadata tag value in an external editor to allow editing values that have line breaks. See configuration option all.editor.

    Only available in the metadata editor.

add-tag
    Add the first parameter as a metadata tag.

    Only available in the metadata editor.

add-value
    Add a new value of the metadata tag that you have currently selected.

    Only available in the metadata editor.

replace-value
    Clear the selected metadata value and start editing.

    Only available in the metadata editor.

del-tag
    Delete the selected tag and value.

    Only available in the metadata editor.

write
    Save all changes made in the metadata editor.

    Only available in the metadata editor.

rules
    Run the rule-based indexers on the current document.

    Only available in the metadata editor.

undo-change
    Undo the most recent change.

    Only available in the metadata editor.

redo-change
    Redo the most recently undone change.

    Only available in the metadata editor.

undo-all-changes
    Discards all changes.

    Only available in the metadata editor.

reset
    Discards all changes, but also deletes the edit history. redo-change will not work after this.

    Only available in the metadata editor.

copy-tag
    Copy the currently selected tag and value to the clipboard. If no parameter is given, the default clipboard is used.

    Only available in the metadata editor.

copy-append-tag
    Add the currently selected tag and value to the clipboard. If no parameter is given, the default clipboard is used.

    Only available in the metadata editor.

paste-tag
    Paste a copied tag from the clipboard. If no parameter is given, the default clipboard's content is used.

    Only available in the metadata editor.

USAGE EXAMPLES

BUGS

To be expected. Please report anything that you find at https://github.com/vonshednob/metaindexmanager or via email to the authors.

Be sure to inspect your logfile for crash reports and add them to the bug report!