Github/filetags
2
0
Fork 1
mirror of https://github.com/novoid/filetags.git synced 2026-02-16 05:54:16 +00:00
Code Issues Projects Releases Packages Wiki Activity

initial documentation of --gui parameter

Browse source
This commit is contained in:
Karl Voit 2025-09-02 17:11:09 +02:00
parent 030ba85c19
commit 107644c91e
2 changed files with 165 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

71
Integration.org
View file

@ -13,7 +13,60 @@ If you have integrated filetags in additional commonly used tools,
please send me a short how-to so that others are able to get the most
out of filetags as well.
** Integrating into Geeqie
** Integration of the GUI-Based Version Using Terminal-Windows
With 2025-09, filetags introduced the =--interactive --gui= option
which provides a GUI dialog for tagging. This simplifies the
integration into third party tools and should run on all major
operating systems as long as you do have Python 3 and [[https://docs.astral.sh/uv/][uv]] installed.
*** Integrating into Geeqie
FIXXME: Take a look at the Nautilus integration. The same principle applies but tool-specific details vary.
*** Integration into Thunar
FIXXME: Take a look at the Nautilus integration. The same principle applies but tool-specific details vary.
*** Integration into Nautilus (GNOME "Filed")
You need to create a file: =~/.local/share/nautilus/scripts/filetags= that holds something like that:
#+BEGIN_SRC sh
#!/usr/bin/env bash
uv --project ${HOME}/src/filetags run ${HOME}/src/filetags/filetags/__init__.py --interactive --gui "$@"
#end
#+END_SRC
Of course, you need to modify the paths according to your situation:
The =--project= parameter points to the main folder of filetags source
code that also contains the file =pyproject.toml= that holds all the
dependencies =uv= is looking for.
The second path is the one to the filetags main executable: =filetags/__init__.py=
This should now provide you a "Script" folder within your "Files" context menu where you can find "filetags".
*** Integration into Windows Explorer
FIXXME: Take a look at the Nautilus integration. The same principle applies but tool-specific details vary.
*** Integration into FreeCommander
FIXXME: Take a look at the Nautilus integration. The same principle applies but tool-specific details vary.
** Integration of the Text-Based Version Using Terminal-Windows
Background: in its original form and for the first decade of its
existance, filetags did not come with a GUI dialog. Therefore, it had
to use some Terminal windows to pop up if filetags was involved from
outside of the command line shell.
These are the integration options for this older method using the
command line and not the GUI:
*** Integrating into Geeqie
I am using [[http://geeqie.sourceforge.net/][geeqie]] for browsing/presenting image files. After I
mark a set of images for adding one or more tags, I just have to
@ -99,7 +152,7 @@ and ~T~ (removing tags), you can define them in geeqie:
I hope this method is as handy for you as it is for me :-)
** Integration into Thunar
*** Integration into Thunar
[[https://en.wikipedia.org/wiki/Thunar][Thunar]] is a popular GNU/Linux file browser for the xfce environment.
@ -130,7 +183,7 @@ If they don't match, following script re-writes ~accels.scm~ with the current ID
: echo "(gtk_accel_path \"<Actions>/ThunarActions/uca-action-$ID\" \"$myshortcut\")" >> $HOME/.config/Thunar/accels.scm
: #+END_SRC
** Integrarion into Nautilus
*** Integrarion into Nautilus (GNOME "Filed")
Nautilus allows scripts to be run directly from its GUI. The program passes the filenames of all selected files into the script under the variable ~$NAUTILUS_SCRIPT_SELECTED_FILE_PATHS~. We will use it to create our "taggify" script.
@ -170,7 +223,7 @@ The folder where we created our .sh file is where Nautilus usually looks for scr
Replace ~/usr/bin/kgx~ with the terminal name we previously copied. Now launch Nautilus, select some files and right click - you should see "Scripts" button in the dropdown list. If you click it, you will be able to click *Taggify* and tag all the selected files at once.
** Integration into Windows Explorer
*** Integration into Windows Explorer
:PROPERTIES:
:CREATED: [2018-03-07 Wed 21:42]
:END:
@ -187,7 +240,7 @@ Execute this in your command line environment:
: integratethis filetags --parameter="--tagtrees --recursive --tagtrees-handle-no-tag no-tags" --displayname "TagTrees recursive"
: integratethis filetags --parameter="--tagtrees --tagtrees-depth 3" --displayname "TagTrees lvl3"
*** Manual Setup
**** Manual Setup
Use this only if the [[https://github.com/novoid/integratethis][integratethis]] method can not be applied:
@ -207,7 +260,7 @@ is one mouse click further away.
You can do both and choose one or the other, depending on how many
files you have selected.
**** Integration into Windows Explorer for single files
***** Integration into Windows Explorer for single files
Use this only if the [[https://github.com/novoid/integratethis][integratethis]] method can not be applied:
@ -266,7 +319,7 @@ print("Successfully written registry file \"register_filetags_for_single_files.r
print("Please check content before executing.")
#+END_SRC
**** Integration into Windows Explorer for single and multiple selected files
***** Integration into Windows Explorer for single and multiple selected files
Use this only if the [[https://github.com/novoid/integratethis][integratethis]] method can not be applied:
@ -321,7 +374,7 @@ If you did not use pip to install, it looks like this:
This way, you got a nice entry in your context sub-menu "Send to"
which is also correctly tagging multiple files at once.
** Integration into FreeCommander
*** Integration into FreeCommander
[[http://freecommander.com/en/summary/][FreeCommander]] is a [[https://en.wikipedia.org/wiki/File_manager#Orthodox_file_managers][orthodox file manager]] for Windows. You can add
filetags as an favorite command:
@ -354,7 +407,7 @@ If you want to assign a different keyboard shortcut than =Ctrl-1= like
overwrite essential shortcuts you're using.
- OK
** Integration into Dired
*** Integration into Dired
:PROPERTIES:
:CREATED: [2018-06-30 Sat 00:00]
:END:

109
README.org
View file

@ -65,7 +65,8 @@ file management:
This tool needs [[http://www.python.org/downloads/][Python 3 to be installed]].
You can install filetags either via [[https://packaging.python.org/tutorials/installing-packages/][pip]] which is the recommended way.
You can install filetags either via [[https://packaging.python.org/tutorials/installing-packages/][pip]] or [[https://docs.astral.sh/uv/][uv]].
Or you can install filetags using the source code, e.g., by cloning
the [[https://github.com/novoid/filetags/][GitHub repository of filetags]].
@ -83,13 +84,20 @@ Now install filetags via [[https://pip.pypa.io/en/stable/][pip]]: ~pip install f
You get updates by executing the very same pip command again.
*** Installation Via Source Code
*** Installation Via Source Code and uv
If you use the GitHub sources (and not pip):
- You need to install depending packages via: ~pip install -r requirements.txt~
- The executable is ~filetags/__init__.py~. You might want to create a
symbolic link named "filetags" to that file.
- The executable is ~filetags/__init__.py~.
- You can install all dependencies and run the script with [[https://docs.astral.sh/uv/][uv]]:
: uv --project ${HOME}/src/filetags run ${HOME}/src/filetags/filetags/__init__.py --interactive --gui "$@"
Of course, you need to modify the paths according to your situation:
The =--project= parameter points to the main folder of filetags source
code that also contains the file =pyproject.toml= that holds all the
dependencies =uv= is looking for.
** Usage
@ -226,6 +234,92 @@ optional arguments:
·
#+END_src
#+BEGIN_SRC
usage: filetags [-h] [-t "STRING WITH TAGS"] [--remove] [-i] [--gui] [-R] [-s]
[--overwrite] [--hardlinks] [-f] [--filebrowser PATH_TO_FILEBROWSER]
[--tagtrees] [--tagtrees-handle-no-tag "treeroot" | "ignore" | "FOLDERNAME"]
[--tagtrees-link-missing-mutual-tagged-items]
[--tagtrees-dir <existing_directory>] [--tagtrees-depth TAGTREES_DEPTH]
[--ln] [--la] [--lu] [--tag-gardening] [-v] [-q] [--version] [FILE ...]
This tool adds or removes simple tags to/from file names.
Tags within file names are placed between the actual file name and
the file extension, separated with " -- ". Multiple tags are
separated with " ":
Update for the Boss -- projectA presentation.pptx
2013-05-16T15.31.42 Error message -- screenshot projectB.png
This easy to use tag system has a drawback: for tagging a larger
set of files with the same tag, you have to rename each file
separately. With this tool, this only requires one step.
Example usages:
filetags --tags="presentation projectA" *.pptx
… adds the tags "presentation" and "projectA" to all PPTX-files
filetags --tags="presentation -projectA" *.pptx
… adds the tag "presentation" to and removes tag "projectA" from all PPTX-files
filetags -i *
… ask for tag(s) and add them to all files in current folder
filetags -r draft *report*
… removes the tag "draft" from all files containing the word "report"
This tools is looking for the optional first text file named ".filetags" in
current and parent directories. Each of its lines is interpreted as a tag
for tag completion. Multiple tags per line are considered mutual exclusive.
Verbose description: http://Karl-Voit.at/managing-digital-photographs/
positional arguments:
FILE One or more files to tag
options:
-h, --help show this help message and exit
-t, --tags "STRING WITH TAGS"
One or more tags (in quotes, separated by spaces) to add/remove
--remove Remove tags from (instead of adding to) file name(s)
-i, --interactive Interactive mode: ask for (a)dding or (r)emoving and name of tag(s)
--gui In interactive mode: use a GUI dialog instead of the text based version
-R, --recursive Recursively go through the current directory and all of its subdirectories. Implemented for --tag-gardening and --tagtrees
-s, --dryrun Enable dryrun mode: just simulate what would happen, do not modify files
--overwrite If a link is about to be created and a previous file/link exists, the old will be deleted if this is enabled.
--hardlinks Use hard links instead of symbolic links. This is ignored on Windows systems. Note that renaming link originals when tagging does not work with hardlinks.
-f, --filter Ask for list of tags and generate links in "/home/rise/.filetags_tagfilter" containing links to all files with matching tags and start the filebrowser. Target directory can be overridden by
--tagtrees-dir.
--filebrowser PATH_TO_FILEBROWSER
Use this option to override the tool to view/manage files (for --filter; default: geeqie). Use "none" to omit the default one.
--tagtrees This generates nested directories in "/home/rise/.filetags_tagfilter" for each combination of tags up to a limit of 2. Target directory can be overridden by --tagtrees-dir. Please note that this may
take long since it relates exponentially to the number of tags involved. Can be combined with --filter. See also http://Karl-Voit.at/tagstore/ and http://Karl-Voit.at/tagstore/downloads/Voit2012b.pdf
--tagtrees-handle-no-tag "treeroot" | "ignore" | "FOLDERNAME"
When tagtrees are created, this parameter defines how to handle items that got no tag at all. The value "treeroot" is the default behavior: items without a tag are linked to the tagtrees root. The
value "ignore" will not link any non-tagged items at all. Any other value is interpreted as a folder name within the tagreees which is used to link all non-tagged items to.
--tagtrees-link-missing-mutual-tagged-items
When the controlled vocabulary holds mutual exclusive tags (multiple tags in one line) this option generates directories in the tagtrees root that hold links to items that have no single tag from
those mutual exclusive sets. For example, when "draft final" is defined in the vocabulary, all items without "draft" and "final" are linked to the "no-draft-final" directory.
--tagtrees-dir <existing_directory>
When tagtrees are created, this parameter overrides the default target directory "/home/rise/.filetags_tagfilter" with a user-defined one. It has to be an empty directory or a non-existing directory
which will be created. This also overrides the default directory for --filter.
--tagtrees-depth TAGTREES_DEPTH
When tagtrees are created, this parameter defines the level of depth of the tagtree hierarchy. The default value is 2. Please note that increasing the depth increases the number of links
exponentially. Especially when running Windows (using lnk-files instead of symbolic links) the performance is really slow. Choose wisely.
--ln, --list-tags-by-number
List all file-tags sorted by their number of use
--la, --list-tags-by-alphabet
List all file-tags sorted by their name
--lu, --list-tags-unknown-to-vocabulary
List all file-tags which are found in file names but are not part of .filetags
--tag-gardening This is for getting an overview on tags that might require to be renamed (typos, singular/plural, ...). See also http://www.webology.org/2008/v5n3/a58.html
-v, --verbose Enable verbose mode
-q, --quiet Enable quiet mode
--version Display version and exit
:copyright: (c) by Karl Voit <tools@Karl-Voit.at>
:license: GPL v3 or any later version
:URL: https://github.com/novoid/filetags
:bugreports: via github or <tools@Karl-Voit.at>
:version: 2025-09-02
#+END_SRC
*** Examples:
: filetags --tags foo a_file_name.txt
@ -345,6 +439,9 @@ key) and propagates into folders of lower hierachy.
- 2018-08-02: added option =--hardlinks= as an alternative for non-Windows systems
- 2019-12-22: added manual file globbing for Windows because of [[https://github.com/novoid/filetags/issues/25][#25]]
- 2021-04-03: added support for =#donotsuggest= lines within =.filetags= files to omit tags from being proposed
- 2025-09-02: added =--gui= option for the =--interactive= invocation.
This is the first GUI dialog of filetags that simplifies integration
into tools very much.
** Get the most out of filetags: controlled vocabulary ~.filetags~
:PROPERTIES:
@ -654,7 +751,7 @@ external commands being added:
- [[http://geeqie.sourceforge.net/][geeqie]], a GNU/Linux image viewer I am using
- [[https://en.wikipedia.org/wiki/Thunar][Thunar]] is a popular GNU/Linux file browser for the xfce environment
- [[https://gitlab.gnome.org/GNOME/nautilus][GNOME Nautilus]] file manager
- [[https://gitlab.gnome.org/GNOME/nautilus][GNOME Nautilus]] file manager ("Files")
- Windows Explorer
- [[http://freecommander.com/en/summary/][FreeCommander]], my recommendated alternative to Windows explorer
- [[https://en.wikipedia.org/wiki/Dired][Dired]], the GNU/Emacs file manager