m2a 2026.3.1.1__tar.gz

m2a-2026.3.1.1/PKG-INFO

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: m2a
+Version: 2026.3.1.1
+Summary: This script moves items (files or directories) containing ISO datestamps like YYYY-MM-DD into a directory stucture for the corresponding year.
+Home-page: https://github.com/novoid/move2archive
+Download-URL: https://github.com/novoid/move2archive/zipball/master
+Author: Karl Voit
+Author-email: Karl Voit <tools@Karl-Voit.at>
+License-Expression: GPL-3.0-or-later
+Project-URL: Homepage, https://github.com/novoid/move2archive
+Keywords: file mangement,filetags,PIM
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.13
+Description-Content-Type: text/plain
+Requires-Dist: pyreadline3>=3.5.4
+Dynamic: author
+Dynamic: download-url
+Dynamic: home-page
+
+* m2a.py
+
+This script moves items (files or directories) containing ISO datestamps
+like ~YYYY-MM-DD~ into a directory stucture for the corresponding year.
+
+You define the base directory either in this script (or using the
+command line argument ~--archivedir~). The convention is, e.g.:
+
+#+begin_src bash
+<archivepath>/2011
+<archivepath>/2011/2011-12-20 Meeting Friends at Barleys
+<archivepath>/2011/2011-12-20 Meeting Friends at Barleys/Tom with Beer.jpeg
+#+end_src
+
+This script extracts the year from the datestamp of each file and
+moves it into the corresponding directory for its year:
+
+#+begin_src bash
+m2a 2010-01-01_Jan2010.txt 2011-02-02_Feb2011.txt
+#+end_src
+... moves ~2010-01-01_Jan2010.txt~ to ~<archivepath>/2010/~
+... moves ~2011-02-02_Feb2011.txt~ to ~<archivepath>/2011/~
+
+OPTIONALLY: you can define a sub-directory name with option ~-d DIR~. If it
+contains no datestamp by itself, a datestamp from the first file of the
+argument list will be used. This datestamp will be put in front of the name:
+
+#+begin_src bash
+m2a  -d "2009-02-15 bar"  one two three
+#+end_src
+... moves all items to: ~<archivepath>/2009/2009-02-15 bar/~
+
+#+begin_src bash
+m2a  -d bar  2011-10-10_one 2008-01-02_two 2011-10-12_three
+#+end_src
+... moves all items to: ~<archivepath>/2011/2011-10-10 bar/~
+
+If you feel uncomfortable you can simulate the behavior using the ~--dryrun~
+option. You see what would happen without changing anything at all.
+
+For the complete usage help, please use the ~--help~ option.
+
+
+- *Target group*: users who are able to use command line tools and who
+  are managing photographs and other event-related files in folder
+  structures.
+- Hosted on github: https://github.com/novoid/move2archive
+
+** Why
+
+There is no integrated software solution for managing photographs
+that will (a) provide you all of the features you will ever want, (b)
+be available for a long period of time, and (c) provide a
+future-prove, platform-independent work-flow.
+
+This is the reason I came up with this method of organizing archive
+files (photographs, scanned PDF files, memories, ...) in such a
+folder structure.
+
+** Installation
+
+Get it from [[https://github.com/novoid/move2archive][GitHub]] or install it via «pip install move2archive».
+
+** Interactive Use
+:PROPERTIES:
+:CREATED:  [2022-01-06 Thu 11:34]
+:END:
+
+If you are using =m2a= in an interactive way, you need to know the
+following behavior difference when you (1) provide a target directory
+and (2) when no specific target directory is provided by you.
+
+Let's use two example files:
+- =2020-07-13T13.55 xkcd about PIM.png=
+- =2022-01-06 screenshot of my editor.png=
+
+Now let's assume those two files are the only PNG files in the current
+directory and the following command line you're using: =m2a *png=
+
+First, let's take a look at the version (1) where you select or enter
+a target directory to file to.
+
+*** Selecting a Target Directory
+
+When asked "Please enter directory basename:" in the interactive
+prompt you're entering "some images".
+
+This will result in *both* files moved to the one target directory
+where the oldest date-stamp is used to determine the year:
+
+- =<archivepath>/2020/2020-07-13 some images/2020-07-13T13.55 xkcd about PIM.png=. 
+- =<archivepath>/2020/2020-07-13 some images/2022-01-06 screenshot of my editor.png=. 
+
+This is because the files are grouped together to be filed to the same
+spot when one single target directory is given.
+
+A handy feature of =m2a= is that it suggest existing folders in the
+=archivepath=. So if you already do have a folder like
+=<archivepath>/2020/2020-07-13 interesting stuff/= and you call =m2a=
+with any file that starts with =2020-07-13...=, it shows a prompt
+like:
+
+: One matching target directory found. Enter "1" if you want to use it:
+:  [1]  2020-07-13 interesting stuff
+
+In the case you want to re-use this directory as the target directory
+for the current files , you simply enter =1= to the prompt and the
+files are moved to that directory. Isn't that handy?
+
+Now, let's compare with (2) when no target directory is given in the
+next section.
+
+*** Not Selecting a Target Directory
+
+This time, you do not enter anything in the target directory prompt
+and you do not select a proposed target by entering a numeric
+shortcut.
+
+This will result in each file moved to its corresponding yearly archive directory:
+
+- =<archivepath>/2020/2020-07-13T13.55 xkcd about PIM.png=
+- =<archivepath>/2022/2022-01-06 screenshot of my editor.png=
+
+*** On the Difference of Behavior
+
+The reasoning behind this different behavior between a specific target
+directory is provided and not is that you can use =m2a= to file away a
+larger group of files to their yearly archive folders without the need
+of filing each one individually or writing a loop command. 
+
+However, when you do provide one single target directory, this is used
+for all files, independent of their date-stamp (using the oldest
+date-stamp).
+
+This might irritate at first but makes perfectly sense if you think
+about it or the alternatives.
+
+** Bonus: integrating into Geeqie (or similar file browsers)
+
+I am using [[http://geeqie.sourceforge.net/][geeqie]] for browsing/presenting image files. For quickly
+moving files to their folders, I mapped this script to ~m~. This way,
+I can go through new image files and move event-related photographs
+very quickly.
+
+Using GNU/Linux, this is quite easy accomplished. The only thing that
+is not straight forward is the need for a wrapper script. The wrapper
+script does provide a shell window for entering the tags.
+
+~vk-m2a-wrapper-with-gnome-terminal.sh~ looks like:
+#+begin_src bash
+#!/bin/sh
+
+/usr/bin/gnome-terminal \
+    --geometry=157x56+330+5  \
+    --hide-menubar \
+    -x /home/vk/bin/m2a --pauseonexit "${@}"
+
+#end
+#+end_src
+
+In ~$HOME/.config/geeqie/applications~ I wrote a desktop file such
+that geeqie shows the wrapper script as external editor to its
+image files:
+
+~$HOME/.config/geeqie/applications/m2a.desktop~ looks like:
+#+begin_src bash
+[Desktop Entry]
+Name=m2a
+GenericName=m2a
+Comment=
+Exec=/home/vk/src/misc/vk-m2a-wrapper-with-gnome-terminal.sh %F
+Icon=
+Terminal=true
+Type=Application
+Categories=Application;Graphics;
+hidden=false
+MimeType=image/*;video/*;image/mpo;image/thm
+Categories=X-Geeqie;
+#+end_src
+
+In order to be able to use the keyboard shortcuts ~m~, you can define
+them in geeqie:
+1. Edit > Preferences > Preferences ... > Keyboard.
+2. Scroll to the bottom of the list.
+3. Double click in the ~KEY~-column of ~m2a~ and choose
+   your desired keyboard shortcut accordingly.
+
+I hope this method is as handy for you as it is for me :-)
+
+* Related tools and workflows
+
+This tool is part of a tool-set which I use to manage my digital files
+such as photographs. My work-flows are described in [[http://karl-voit.at/managing-digital-photographs/][this blog posting]]
+you might like to read.
+
+In short:
+
+For *tagging*, please refer to [[https://github.com/novoid/filetags][filetags]] and its documentation.
+
+See [[https://github.com/novoid/date2name][date2name]] for easily adding ISO *time-stamps or date-stamps* to
+files.
+
+For *easily naming and tagging* files within file browsers that allow
+integration of external tools, see [[https://github.com/novoid/appendfilename][appendfilename]] (once more) and
+[[https://github.com/novoid/filetags][filetags]].
+
+Moving to the archive folders is done using [[https://github.com/novoid/move2archive][move2archive]].
+
+Having tagged photographs gives you many advantages. For example, I
+automatically [[https://github.com/novoid/set_desktop_background_according_to_season][choose my *desktop background image* according to the
+current season]].
+
+Files containing an ISO time/date-stamp gets indexed by the
+filename-module of [[https://github.com/novoid/Memacs][Memacs]].
+
+Here is [[https://glt18-programm.linuxtage.at/events/321.html][a 45 minute talk I gave]] at [[https://glt18.linuxtage.at/][Linuxtage Graz 2018]] presenting the
+idea of and workflows related to appendfilename and other handy tools
+for file management:
+
+[[https://media.ccc.de/v/GLT18_-_321_-_en_-_g_ap147_004_-_201804281550_-_the_advantages_of_file_name_conventions_and_tagging_-_karl_voit/][bin/2018-05-06 filetags demo slide for video preview with video button -- screenshots.png]]
+
+Other projects with similar features:
+
+- https://github.com/velvet-jones/imgfiler/
+
+* How to Thank Me
+
+I'm glad you like my tools. If you want to support me:
+
+- Send old-fashioned *postcard* per snailmail - I love personal feedback!
+  - see [[http://tinyurl.com/j6w8hyo][my address]]
+- Send feature wishes or improvements as an issue on GitHub
+- Create issues on GitHub for bugs
+- Contribute merge requests for bug fixes
+- Check out my other cool [[https://github.com/novoid][projects on GitHub]]
+
+
+
+* Local Variables                                                  :noexport:
+# Local Variables:
+# mode: auto-fill
+# mode: flyspell
+# eval: (ispell-change-dictionary "en_US")
+# End:

m2a-2026.3.1.1/README.org

@@ -0,0 +1,244 @@
+* m2a.py
+
+This script moves items (files or directories) containing ISO datestamps
+like ~YYYY-MM-DD~ into a directory stucture for the corresponding year.
+
+You define the base directory either in this script (or using the
+command line argument ~--archivedir~). The convention is, e.g.:
+
+#+begin_src bash
+<archivepath>/2011
+<archivepath>/2011/2011-12-20 Meeting Friends at Barleys
+<archivepath>/2011/2011-12-20 Meeting Friends at Barleys/Tom with Beer.jpeg
+#+end_src
+
+This script extracts the year from the datestamp of each file and
+moves it into the corresponding directory for its year:
+
+#+begin_src bash
+m2a 2010-01-01_Jan2010.txt 2011-02-02_Feb2011.txt
+#+end_src
+... moves ~2010-01-01_Jan2010.txt~ to ~<archivepath>/2010/~
+... moves ~2011-02-02_Feb2011.txt~ to ~<archivepath>/2011/~
+
+OPTIONALLY: you can define a sub-directory name with option ~-d DIR~. If it
+contains no datestamp by itself, a datestamp from the first file of the
+argument list will be used. This datestamp will be put in front of the name:
+
+#+begin_src bash
+m2a  -d "2009-02-15 bar"  one two three
+#+end_src
+... moves all items to: ~<archivepath>/2009/2009-02-15 bar/~
+
+#+begin_src bash
+m2a  -d bar  2011-10-10_one 2008-01-02_two 2011-10-12_three
+#+end_src
+... moves all items to: ~<archivepath>/2011/2011-10-10 bar/~
+
+If you feel uncomfortable you can simulate the behavior using the ~--dryrun~
+option. You see what would happen without changing anything at all.
+
+For the complete usage help, please use the ~--help~ option.
+
+
+- *Target group*: users who are able to use command line tools and who
+  are managing photographs and other event-related files in folder
+  structures.
+- Hosted on github: https://github.com/novoid/move2archive
+
+** Why
+
+There is no integrated software solution for managing photographs
+that will (a) provide you all of the features you will ever want, (b)
+be available for a long period of time, and (c) provide a
+future-prove, platform-independent work-flow.
+
+This is the reason I came up with this method of organizing archive
+files (photographs, scanned PDF files, memories, ...) in such a
+folder structure.
+
+** Installation
+
+Get it from [[https://github.com/novoid/move2archive][GitHub]] or install it via «pip install move2archive».
+
+** Interactive Use
+:PROPERTIES:
+:CREATED:  [2022-01-06 Thu 11:34]
+:END:
+
+If you are using =m2a= in an interactive way, you need to know the
+following behavior difference when you (1) provide a target directory
+and (2) when no specific target directory is provided by you.
+
+Let's use two example files:
+- =2020-07-13T13.55 xkcd about PIM.png=
+- =2022-01-06 screenshot of my editor.png=
+
+Now let's assume those two files are the only PNG files in the current
+directory and the following command line you're using: =m2a *png=
+
+First, let's take a look at the version (1) where you select or enter
+a target directory to file to.
+
+*** Selecting a Target Directory
+
+When asked "Please enter directory basename:" in the interactive
+prompt you're entering "some images".
+
+This will result in *both* files moved to the one target directory
+where the oldest date-stamp is used to determine the year:
+
+- =<archivepath>/2020/2020-07-13 some images/2020-07-13T13.55 xkcd about PIM.png=. 
+- =<archivepath>/2020/2020-07-13 some images/2022-01-06 screenshot of my editor.png=. 
+
+This is because the files are grouped together to be filed to the same
+spot when one single target directory is given.
+
+A handy feature of =m2a= is that it suggest existing folders in the
+=archivepath=. So if you already do have a folder like
+=<archivepath>/2020/2020-07-13 interesting stuff/= and you call =m2a=
+with any file that starts with =2020-07-13...=, it shows a prompt
+like:
+
+: One matching target directory found. Enter "1" if you want to use it:
+:  [1]  2020-07-13 interesting stuff
+
+In the case you want to re-use this directory as the target directory
+for the current files , you simply enter =1= to the prompt and the
+files are moved to that directory. Isn't that handy?
+
+Now, let's compare with (2) when no target directory is given in the
+next section.
+
+*** Not Selecting a Target Directory
+
+This time, you do not enter anything in the target directory prompt
+and you do not select a proposed target by entering a numeric
+shortcut.
+
+This will result in each file moved to its corresponding yearly archive directory:
+
+- =<archivepath>/2020/2020-07-13T13.55 xkcd about PIM.png=
+- =<archivepath>/2022/2022-01-06 screenshot of my editor.png=
+
+*** On the Difference of Behavior
+
+The reasoning behind this different behavior between a specific target
+directory is provided and not is that you can use =m2a= to file away a
+larger group of files to their yearly archive folders without the need
+of filing each one individually or writing a loop command. 
+
+However, when you do provide one single target directory, this is used
+for all files, independent of their date-stamp (using the oldest
+date-stamp).
+
+This might irritate at first but makes perfectly sense if you think
+about it or the alternatives.
+
+** Bonus: integrating into Geeqie (or similar file browsers)
+
+I am using [[http://geeqie.sourceforge.net/][geeqie]] for browsing/presenting image files. For quickly
+moving files to their folders, I mapped this script to ~m~. This way,
+I can go through new image files and move event-related photographs
+very quickly.
+
+Using GNU/Linux, this is quite easy accomplished. The only thing that
+is not straight forward is the need for a wrapper script. The wrapper
+script does provide a shell window for entering the tags.
+
+~vk-m2a-wrapper-with-gnome-terminal.sh~ looks like:
+#+begin_src bash
+#!/bin/sh
+
+/usr/bin/gnome-terminal \
+    --geometry=157x56+330+5  \
+    --hide-menubar \
+    -x /home/vk/bin/m2a --pauseonexit "${@}"
+
+#end
+#+end_src
+
+In ~$HOME/.config/geeqie/applications~ I wrote a desktop file such
+that geeqie shows the wrapper script as external editor to its
+image files:
+
+~$HOME/.config/geeqie/applications/m2a.desktop~ looks like:
+#+begin_src bash
+[Desktop Entry]
+Name=m2a
+GenericName=m2a
+Comment=
+Exec=/home/vk/src/misc/vk-m2a-wrapper-with-gnome-terminal.sh %F
+Icon=
+Terminal=true
+Type=Application
+Categories=Application;Graphics;
+hidden=false
+MimeType=image/*;video/*;image/mpo;image/thm
+Categories=X-Geeqie;
+#+end_src
+
+In order to be able to use the keyboard shortcuts ~m~, you can define
+them in geeqie:
+1. Edit > Preferences > Preferences ... > Keyboard.
+2. Scroll to the bottom of the list.
+3. Double click in the ~KEY~-column of ~m2a~ and choose
+   your desired keyboard shortcut accordingly.
+
+I hope this method is as handy for you as it is for me :-)
+
+* Related tools and workflows
+
+This tool is part of a tool-set which I use to manage my digital files
+such as photographs. My work-flows are described in [[http://karl-voit.at/managing-digital-photographs/][this blog posting]]
+you might like to read.
+
+In short:
+
+For *tagging*, please refer to [[https://github.com/novoid/filetags][filetags]] and its documentation.
+
+See [[https://github.com/novoid/date2name][date2name]] for easily adding ISO *time-stamps or date-stamps* to
+files.
+
+For *easily naming and tagging* files within file browsers that allow
+integration of external tools, see [[https://github.com/novoid/appendfilename][appendfilename]] (once more) and
+[[https://github.com/novoid/filetags][filetags]].
+
+Moving to the archive folders is done using [[https://github.com/novoid/move2archive][move2archive]].
+
+Having tagged photographs gives you many advantages. For example, I
+automatically [[https://github.com/novoid/set_desktop_background_according_to_season][choose my *desktop background image* according to the
+current season]].
+
+Files containing an ISO time/date-stamp gets indexed by the
+filename-module of [[https://github.com/novoid/Memacs][Memacs]].
+
+Here is [[https://glt18-programm.linuxtage.at/events/321.html][a 45 minute talk I gave]] at [[https://glt18.linuxtage.at/][Linuxtage Graz 2018]] presenting the
+idea of and workflows related to appendfilename and other handy tools
+for file management:
+
+[[https://media.ccc.de/v/GLT18_-_321_-_en_-_g_ap147_004_-_201804281550_-_the_advantages_of_file_name_conventions_and_tagging_-_karl_voit/][bin/2018-05-06 filetags demo slide for video preview with video button -- screenshots.png]]
+
+Other projects with similar features:
+
+- https://github.com/velvet-jones/imgfiler/
+
+* How to Thank Me
+
+I'm glad you like my tools. If you want to support me:
+
+- Send old-fashioned *postcard* per snailmail - I love personal feedback!
+  - see [[http://tinyurl.com/j6w8hyo][my address]]
+- Send feature wishes or improvements as an issue on GitHub
+- Create issues on GitHub for bugs
+- Contribute merge requests for bug fixes
+- Check out my other cool [[https://github.com/novoid][projects on GitHub]]
+
+
+
+* Local Variables                                                  :noexport:
+# Local Variables:
+# mode: auto-fill
+# mode: flyspell
+# eval: (ispell-change-dictionary "en_US")
+# End: