m2a 2026.3.1.1

This script moves items (files or directories) containing ISO datestamps like YYYY-MM-DD into a directory stucture for the corresponding year.

* 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: