search

bassmanitram / actions-for-nautilus

An extension to the Gnome "Files" file manager that allows you to add arbitrary actions to the file selection context menu.
Apache License 2.0
177 stars 17 forks source link
files gnome-desktop gnome-files nautilus nautilus-extension

readme

IMPORTANT NOTE All users of releases 1.6.0 and before should update their installations to release 1.6.1 as soon as possible due to a security issue.

Actions For Nautilus

An extension to the Gnome Files file manager (otherwise known as Nautilus) that allows you to add arbitrary actions to the Gnome Files selection context menu.

This extension is a "replacement" for the now-defunct Nautilus file manager functionality of the filemanager/nautilus-actions project.

The extension supports many of the most commonly used features of the original extension project, including:

It is also much better at executing commands in a shell than the original extension, allowing for the construction of pipelines and loops, as well as the use of more complex shell expressions, without the need for writing wrapper scripts.

A configuration application by the name "Actions For Nautilus Configurator" is installed into your desktop applications collection. When you first use the configurator, if no existing configuration file is found, the delivered sample configuration will be installed.

The project has a wiki that is used to share tips and tricks and useful configuration examples.

Installation

Debian-based systems

Debian packages of the most recent releases are provided in the dist folder.

Simply download the package, install with your package installer, then launch the Actions For Nautilus Configurator application from your applications list in order to start building a configuration based upon the delivered sample.

To enable the extension after installation, you will need to restart Nautilus/Files:

should do it.

Suggested Additional Packages

The Debian package specifies the following Suggests dependencies that will greatly enhance the utility of the extension as well as allow the delivered sample configuration to work on first launch:

It is highly recommended to install these extra packages.

Manual Installation

Install Dependencies

Firstly, of course, the extension relies upon GNOME and GNOME Files (aka Nautilus) being installed.

Then it relies on python 3+, nautilus-python, and certain process management tools (which are likely already installed but just in case :)).

Download & Install the Extension

To install the extension manually, then, you will need to follow these steps:

  1. git clone https://github.com/bassmanitram/actions-for-nautilus.git
  2. cd actions-for-nautilus
  3. make install to install for only your use, or sudo make install_global to install for all users.
  4. You may have to restart the Gnome shell in order to see the configuration application in your desktop applications list

If you don't have the git or make commands in your system, simply install them in the same way you installed the other dependencies.

On first installation, you won't see anything different in the Nautilus context menus, because you need to have a working configuration for anything to change. The sample configuration will be installed for the user simply by starting the configuration UI.

Uninstallation

  1. cd path/to/actions-for-nautilus
  2. make uninstall if you installed for only your use, or sudo make uninstall_global if you installed for all users.
  3. You may have to restart the Gnome shell in order to remove the configuration application from your desktop applications list

Sample configuration

The delivered sample configuration file is copied to 

${HOME}/.local/share/actions-for-nautilus/config.json

when you first start the configuration UI, if there is no existing configuration.

The configuration contains examples of command and menu construction, including:

The configured commands rely on a few extra dependencies that need to be installed if you want to see the sample configuration working properly:

Again, these can be installed using your platform package manager as shown above.

It is also possible that the semantics of the more complex command structures rely upon shell features that, if you are not using BASH as your system shell, will not work for you.

The Gnome Terminal "No Close" profile

When executing the gnome-terminal command, the sample configuration references a gnome-terminal profile named "No Close".

This is not a standard profile, but is a useful one to define in that the terminal doesn't close when the command it is running ends, allowing you to see command output and/or to relaunch the command.

You can create this profile as follows:

Configuration UI

When you install this extension, a configuration application is installed into your local desktop Applications collection.

To start the application:

The application will open in your default Web Browser. It will present the current configuration (creating one from the delivered sample if no configuration yet exists for the user).

The UI should be pretty self-explanatory - you can add, delete, move and modify Menus and Commands at will.

There is also an embedded JSON source editor with syntax checking should you wish to perform actions not supported by the main UI (such as copy/paste of actions).

Simply close the web page to quit the configurator.

NOTE the configurator web application NEVER communicates outside of your own system unless you click on an external link referenced in the help information.

Configurator help

The UI includes integrated help that can be accessed in one of two ways:

When both the configurator and the help information are displayed, the viewport sizes can be adjusted by dragging the line that separates them.

To close the help information, simply click on the Hide Help button (which is the Show Help button with the label modified when the help information is being displayed).

Saving your changes

In order to save configuration changes, click on the Save Config button. Your changes should be visible in Nautilus after about 30 seconds (the timeout for the internal config file change watcher).

The existing configuration file is backed up before being overridden by a saved configuration. You can reinstate an older configuration by opening Nautilus/Files, navigating to the folder...

${HOME}/.local/share/nautilus-python/extensions/actions-for-nautilus

and replacing your current config.json file with any of the backed up copies. Again, changes will take effect after a maximum of about 30 seconds.

Configuration reference

The configuration is specified in a JSON text file named config.json located in

${HOME}/.local/share/actions-for-nautilus

The extension is delivered with a strict valid JSON Schema that describes exactly how the configuration file needs to be built.

(Note that there is also a second JSON Schema delivered. This is for internal use by the configurator and should not be considered a canonical description of the extension configuration file).

Top level structure

The top level structure in the configuration file must be a JSON object which is expected to contain a property named actions whose value is, itself, an array of objects, and a string property named sort:

{
  "actions": [
    {
      ...
    },
    "sort": "manual or auto"
  ]
}

The sort property is optional and indicates the approach to use for sorting the actions presented by the top level menu. The allowed values are:

The default value is - manual

The actions array contains the configuration of each action to be presented in the top level menu

Each element of the array is then an object (and action) which, primarily, must have a property named type whose value is either command or menu, and a property named label whose value is the text that you wish to see in the Nautilus context menu.

    {
      "type": "command",
      "label": "My Command",
      ...
    },
    {
      "type": "menu",
      "label": "My Sub Menu",
      ...
    },
    ...

The subsequent sections describe these action objects in detail.

Menu actions

Actions with a type property of menu define "sub menu" actions that, when clicked on, expose a nested menu of further actions, themselves being command actions or further nested menus.

    ...
    {
      "type": "menu",
      "label": "My Sub Menu",
      "actions": [
        ...
      ],
      "sort": "manual or auto"
    },
    ...

Menu actions are expected to contain two additional properties:

When the Nautilus/Files context menu is activated for a selection, the extension assesses all the commands configured within a menu to establish if the commands are relevant for the current selection. If no commands are found to be relevant, then the menu does not appear in the Nautilus/Files context menu.

Command actions

Actions with a type property of command define actions that, when clicked on, execute a command.

    ...
    {
      "type": "command",
      "label": "My Command",
      command_line: "my-script.sh %F %c",
      cwd: "%d",
      use_shell: true,
      min_items: 1,
      max_items: 1,
      "mimetypes": [
        ...
      ],
      "filetypes": [
        ...
      ],
      "path_patterns": [
        ...
      ]
    },
    ...

These are expected to have the following additional properties:

With the mimetypes, filetypes and path_patterns filter lists, all selected files must match at least one non-negated rule (if there are any non-negated rules), while matching none of the negated rules, in order for the associated action to appear in the context menu.

Place holders

All the command line and cwd placeholders implemented by the filemanager/nautilus-actions project are implemented by this extension, with the same semantics:

Placeholder Description Repetition
%b the basename of the first selected item (e.g. my-file.txt) SINGULAR
%B space-separated list of the %b values of all selected items PLURAL
%c the number of items in the selection ANY
%d the full path to the directory holding the first selected item (e.g. /home/me/my-first-dir/my-second-dir SINGULAR
%D space-separated list of the %d values of all selected items PLURAL
%f the full path of the first selected item (e.g. /home/me/my-first-dir/my-second-dir/my-file.txt SINGULAR
%F space-separated list of the %f values of all selected items PLURAL
%h the host name from the URI of the first selected item ANY
%m the mimetype of the first selected item (e.g. text/plain) SINGULAR
%M space-separated list of the %m values of all selected items PLURAL
%n the username from the URI of the first selected item ANY
%o no-op operator which forces a SINGULAR form of execution - see below for more details SINGULAR
%O no-op operator which forces a PLURAL form of execution - see below for more details PLURAL
%p the port from the URI of the first selected item ANY
%s the URI scheme from the URI of the first selected item (e.g. file) ANY
%u the URI of the first selected item (e.g. file:///home/me/my-first-dir/my-second-dir/my-file.txt) SINGULAR
%U space-separated list of the %u values of all selected items PLURAL
%w the basename of the first selected item without it's extension (e.g. my-file) SINGULAR
%W space-separated list of the %w values of all selected items PLURAL
%x the extension of the first selected item without it's extension (e.g. txt) SINGULAR
%X space-separated list of the %x values of all selected items PLURAL
%% the % character ANY

Any embedded spaces found in the individual values are 'escaped' to ensure that the shell or system recognizes each value as an independent and complete argument to the command.

The meaning of the Repetition value is explained in the next section.

Execution behavior

The filemanager/nautilus-actions project implemented a feature whereby a configured command could be executed once only, regardless of the number items in the selection, or once for each item in the selection.

This extension implements the same feature with the same semantics.

The decision as to which mode is desired is based upon the first placeholder found in the command_line property value for the activated action:

Additionally, if the command is to be executed once for each item in the selection then any placeholder with a Repetition value of SINGULAR is resolved to the corresponding value for the selected item for which the command is being executed.

Placeholders with Repetition values that are not SINGULAR are resolved to their full values for each execution of the command.

An example

This example is taken directly from the filemanager/nautilus-actions project documentation:

Say the current folder is /data, and the current selection contains the three files pierre, paul and jacques.

If we have requested echo %b, then the following commands will be successively run:

echo pierre
echo paul
echo jacques

This is because %b marks a SINGULAR parameter. The command is then run once for each of the selected items.

Contrarily, if we have requested echo %B, then the following command will be run:

echo pierre paul jacques

This is because %B marks a PLURAL parameter. The command is then run only once, with the list of selected items as arguments.

If we have requested echo %b %B, then the following commands will be successively run:

echo pierre pierre paul jacques
echo paul pierre paul jacques
echo jacques pierre paul jacques

This is because the first relevant parameter is %b, and so the command is run once for each selected item, replacing at each occurrence the %b parameter with the corresponding item. The second parameter is computed and added as arguments to the executed command.

And if we have requested echo %B %b, then the following command will be run:

echo pierre paul jacques pierre

This is because the first relevant parameter here is %B. The command is then run only once, replacing %B with the space-separated list of basenames. As the command is only run once, the %b is substituted only once with the (first) basename.

Diagnostics

Error messages are sent to the Nautilus stdout or stderr - including errors found in the configuration file (such as invalid JSON format).

Additionally, the property debug can be set in the top level object, with a value of true or false (the default). When set to true further debug information is printed to the Nautilus stdout.

In order to see that output you will need to start Nautilus in a special way from a terminal emulator (e.g. gnome-terminal):

# Stop Nautilus
nautilus -q  
# Restart with `stdout` and `stderr` being displayed at the terminal
nautilus --no-desktop

Note that, in order to stop this special execution mode, you will need to either close the terminal emulator, or, from another emulator run the nautilus -q command.

Acknowledgments

The main acknowledgement is, of course, to the original Nautilus Actions extension, later renamed to Filemanager Actions to reflect its wider applicability (Nemo, for example).

Unfortunately, this extension is no longer maintained and is no longer functional since Nautilus 42.2 (itself now renamed Gnome Files, though the underlying programming objects are still in the Nautilus namespace).

I was tempted to take over the maintenance of that project, but was put off by its complex C implementation (I'm a perfectly competent C programmer, mind!).

I was convinced that a much less complex implementation of most of the main functionality was possible using Python and the glue to Nautilus found in the nautilus-python framework, and by using a far more semantically relevant configuration format such as JSON and adapting an existing JSON editor UI rather than building a configuration UI from scratch.

I think I have proved my point :)

Another big acknowledgement is of Christoforos Aslanov whose Nautilus Copy Path extension provided the inspiration and template for the original POC of this extension, and whose project structure, installation procedure and doc I initially mercilessly ripped off :)... and I'm even disrespectful enough to have provided an alternative to his extension in my own sample config!

Thanks and apologies, Christoforos.

The JSON Schema-based editor JSON-Editor is an amazing find! The configurator is, in effect, an instance of that editor with a few tweaks to make it look and feel a bit more natural for this use case!

The embedded JSON source editor is the ACE source editor - another amazing project which was so easy to embed that one wonders why JSON-Editor doesn't use that for its own JSON source editing feature - I feel a PR coming on :).

So, a BIG shout-out to those two projects!