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.
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:
- structuring context menu items for Nautilus File Manager selections including nested sub menus
- filtering the displayed items based on:
- number of files in the selection,
- user's access permissions for the selected files,
- mimetypes of the selected files (matching and non-matching conditions supported, as well as mimetype globs),
- basic filetypes of the selected files - e.g. 'file', 'directory', 'symbolic-link' ... - (matching and non-matching conditions supported),
- full path pattern matching, expressed as glob patterns or regular expressions, again with support for matching and non-matching conditions.
- execution of an arbitrary command/script when a menu item is activated, with
the same "PLURAL" and "SINGULAR" semantics as the
filemanager/nautilus-actionsproject - support for all the command line placeholders implemented by the
filemanager/nautilus-actionsproject, with the same semantics
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.
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:
Alt F2nautilus -q
should do it.
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:
xclip- a command line tool for managing the X clipboardszenity- a Gnome UI toolkit for shell scripts
It is highly recommended to install these extra packages.
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 :)).
- Fedora
sudo dnf install nautilus-python python3-gobject procps-ng js-jquery - Ubuntu
sudo apt install python3-nautilus python3-gi procps libjs-jquery - Arch
sudo pacman -S python-nautilus python-gobject procps-ng jquery
To install the extension manually, then, you will need to follow these steps:
git clone https://github.com/bassmanitram/actions-for-nautilus.gitcd actions-for-nautilusmake installto install for only your use, orsudo make install_globalto install for all users.- 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.
cd path/to/actions-for-nautilusmake uninstallif you installed for only your use, orsudo make uninstall_globalif you installed for all users.- You may have to restart the Gnome shell in order to remove the configuration application from your desktop applications list
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:
- contextual submenus,
- mimetype, file type, and selection count conditions,
- the use of command pipelines,
- exploiting
$(...)/backtick command and argument substitution. - ...
The configured commands rely on a few extra dependencies that need to be installed if you want to see the sample configuration working properly:
gedit- the standard Gnome editor - you probably already have thisgnome-terminal- the standard Gnome terminal emulator (for now) - you probably have this too.xclip- a command line tool for managing the X clipboardszenity- a Gnome UI toolkit for shell scripts
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.
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:
- Open the
gnome-terminalapplication - Find the
Preferencesdialog (either a menu item or click on the...button, then onPreferences) - Click on the + next to the word
Profiles - Give the new profile the name
No Close - Click on the
Commandtab - Ensure that the
When command exits:option is set toHold terminal open - Configure anything else you need concerning the profile behavior and look and feel
When you install this extension, a configuration application is installed into your local desktop Applications collection.
To start the application:
- Open your Applications collection navigator (menu, panel, ...)
- Find Actions For Nautilus Configurator
- Click on it
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.
The UI includes integrated help that can be accessed in one of two ways:
- Click on the
Show Helpbutton to open the help viewport to the right of the main configurator UI, positioned at the beginning of the help information. - Click on any of the ⓘ icons to open the help viewport to the right of the main configurator UI, positioned at the information pertaining to the UI element to which the ⓘ icon is attached.
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).
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.
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).
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:
manual- The extension leaves the items in the order in which they appear in the configurationauto- The extension sorts the items in alphanumeric order
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.
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:
-
actions- REQUIRED - an array of elements each of which follows the same pattern as the elements contained by the configuration's rootactionsproperty -
sort- OPTIONAL - The approach to use for sorting the actions presented by the menumanual- The extension leaves the items in the order in which they appear in the configurationauto- The extension sorts the items in alphanumeric order
Default -
manual
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.
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:
-
command_line- REQUIRED - the system command the should be executed when the menu item is clicked on, expressed as a string.The command may contain place holder expressions that are expanded to hold details of the selected files that are passed as arguments to the command.
The full set of placeholders implemented by the
filemanager/nautilus-actionsproject are supported, with the same semantics - these are further documented below.Note that, when using the
use_shelloption (below), the command line can be just about anything you can enter at a shell prompt - including the following features:- Pipelines
$(...)or "backtick" command and argument generation/expansion- Environment variable resolution
- Loops
- ...
See the sample configuration for a few examples.
-
cwd- OPTIONAL - the working directory that the command should "run in" expressed as a stringThis too can contain place holder expressions, though obviously they should resolve to a single valid directory name
Default - undefined
-
use_shell- OPTIONAL - a boolean value (trueorfalse) that indicates whether the command should be run by the default system shell. If the command is a shell script, or relies on any shell expansion semantics, you should set the value of this property totrue.Default -
false -
filetypes- OPTIONAL - the general filetypes of the selected files for which this action is to be displayed (or for which the action is not to be displayed)The value should be a JSON list of strings each one of which should have one of the following values:
unknown- for files of an unknown typedirectory- for directoriesfile- for standard filessymbolic-link- for symbolic linksspecial- for special files (pipes, devices, ...)standard- shorthand for directories, standard files, and symbolic links
Again, these can be prefixed with a
!character to indicate that the selected files should not be of that type.Only the first appearance of a specific filetype (regardless of any
!"not" prefix) is taken into account.Default - all filetypes are accepted
-
min_items- OPTIONAL - the minimum number of items in the selection for which this action will be displayed.For example, if the command is expected to, say, compare a number of files, it doesn't make sense for the action to be displayed when less than two files are in the selection. In that case, you would set the value of this property to
2which would prevent the action from appearing in the context menu when only one file is in the selection.If specified, the value must be greater than zero.
If the value of
max_itemsis greater than zero, the value of this property must be less than or equal to the value ofmax_items.Default - 1
-
max_items- OPTIONAL - the maximum number of items in the selection for which this action will be displayed.For example, if the command is expected to, say, start an HTTP server in a selected directory, it doesn't make sense for the action to be displayed when more than one directory is in the selection. Therefore, in this case, you would set the value of this property to
1, which would prevent the action from appearing in the context menu when more than one directory is in the selection.A value of zero denotes
unlimited.If the value is greater than zero, the value of the
min_itemsproperty must be less than or equal to this value.Default - unlimited
-
mimetypes- OPTIONAL - the mimetypes of the selected files for which this action is to be displayed (or for which the action is not to be displayed).The value should be a JSON list of strings in the following format:
*/*or*- meaning that the action can be displayed for all mimetypestype/subtype- to display the action for files of a specific mimetypetype/*- to display the action for files whose mimetypes are any subtype of a specific type!type/subtype- to not display the action for files of a specific mimetype!type/*- to not display the action for files whose mimetypes are any subtype of a specific type
All files in the selection must match an action's mimetype rules for that action to be displayed. Mixing "not" rules with ... well, "not not" rules, can be confusing.
Only the first appearance of a specific rule (regardless of any
!"not" prefix) is taken into account.Default - all mimetypes are accepted
-
path_patterns- OPTIONAL - a list of glob or regular expression patterns against which the full paths of the selected files are to be matched.The value should be a JSON list of strings, each in one of the following formats:
-
a "glob" expression - a simple but limited string pattern expression syntax that is used by many UNIX shell commands as well as the shell itself, consisting of the following placeholders:
*indicating zero or more characters?indicating a single character[abc]indicating one of the characters between the brackets[!abc]indicating none of the characters between the brackets
Quite often this syntax is all that you need in order to express the pattern you wish to match against.
Note that globs inherently match against the whole path.
-
re:followed by a regular expression (WITHOUT/delimiters) - more complex needs can be expressed as regular expressions.Note that regular expressions do not inherently match against the whole path.
This means that if any part of a selected file path matches the regular expression, the path will be accepted.
If you want to match against the whole path, start your regular expression with
^and end it with$.
Either pattern format can be prefixed with
!in order to negate the pattern.All files in the selection must match an action's path pattern rules for that action to be displayed. Mixing "not" rules with ... well, "not not" rules, can be confusing.
Only the first appearance of a specific rule (regardless of any
!"not" prefix) is taken into account.The accepted glob syntax is fully documented here. The accepted Regular Expression syntax is fully documented here .
Default - all file paths are accepted
-
-
permissions- OPTIONAL - an indicator of the minimum access permissions that the user must have for the selected files in order for the associated action to be presented in the Nautilus context menu.The valid values are:
read- the user must at least have read permissions for the selected filesread-write- the user must at least have read and write permissions for the selected filesread-execute- For files, the user must at least have read and execute permissions for the selected files For folders, the user must at least have read and navigational permissions for the selected foldersread-write-execute- the user must have full read, write and execution/navigation permissions for the selected files
Any other value will disable the permissions check.
Default - user access permissions are not checked.
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.
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.
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:
- If the placeholder has a
Repetitionproperty ofSINGULAR, the command is executed once for each item in the selection. - If the placeholder has a
Repetitionproperty ofPLURAL, the command is executed once only. - If the placeholder has a
Repetitionproperty ofANY, then the next placeholder is examined. - If no placeholder with a
SINGULARorPLURALrepetition value is found in the command, then the command is executed only once.
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.
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 filespierre,paulandjacques.If we have requested
echo %b, then the following commands will be successively run:echo pierre echo paul echo jacquesThis is because
%bmarks 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 jacquesThis is because
%Bmarks 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 jacquesThis is because the first relevant parameter is
%b, and so the command is run once for each selected item, replacing at each occurrence the%bparameter 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 pierreThis is because the first relevant parameter here is
%B. The command is then run only once, replacing%Bwith the space-separated list of basenames. As the command is only run once, the%bis substituted only once with the (first) basename.
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.
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!
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent