| organizebydate - Rename files based on their date-time |
organizebydate - Rename files based on their date-time
organizebydate [OPTIONS] PATHS [FIND-PARAM]
Organize files by date and time, typically into a directory structure.
PATHS are file and/or directory paths.
FIND-PARAM are find(1) expressions (predicates) to filter which files to work on,
or -H, -L, or -P options - see find(1).
Target path name template using strftime(3) macros.
Default: %Y/%m/%d/
Extra macros accepted:
Move or copy files. Default is copy.
Move successfully copied files according to TMPL template. This is useful only with --copy. Default is not to move away successfully copied filed. This is useful if you want to keep backed up files on the source too but in another directory so they won't be processed again.
Overwrite already existing target files. Default is to silently ignore them. Note, this affects only --copy and --move, not --handler.
Execute PROG to handle files 1-by-1 instead of internal copy or move.
You may do --handler "rsync -Pvit --inplace --mkpath" --template HOSTNAME:PATH to upload via ssh/rsync
(beware, --set-*time > and conflicting filename checking work only on local paths)
or implement any file transfer method here.
Arguments passed (after those which are given in PROG) are
first, the source file path, and second, the target file path.
Conflicting target path is still checked and resolver is run before PROG
if --conflict-resolver-cmd or --conflict-resolver-script is specified;
if not, PROG should implement conflicting file name resolution logic.
Run a custom conflict resolver logic on already existing target files.
Unless conflict resolver is given, organizebydate(1) ignores conflicts silently
or overwrites target unconditionally if --overwrite is specified.
The conflict resolver can either be a single word command
or a command and arguments - when CMD contains IFS chars (like space)
(in this case you can not pass arguments themself containing spaces to the command
because each space-delimited word goes to a separate argument),
or a whole bash(1) script if --conflict-resolver-script is given.
SCRIPT is run as a separate command too, not in organizebydate(1)'s own shell context.
COMMAND ARGUMENTS
Arguments passed to conflict resolver command/script (after the arguments included in CMD, if any) are the source file's path first and the target path secondly:
EXAMPLES
--conflict-resolver-cmd some-command # runs this: some-command SOURCE TARGET --conflict-resolver-cmd "some-command --option x" # runs this: some-command --option x SOURCE TARGET
--conflict-resolver-cmd "some-command --option \"a and b\"" # WRONG: "a and b" goes into 3 separate arguments, not one --conflict-resolver-script "some-command --option \"a and b\" \"$@\"" # RIGHT: runs this within a bash script # and the end this in ran: some-command --option "a and b" SOURCE TARGET
ENVIRONMENT
Environment variables passed to conflict resolver programms:
ORGANIZEBYDATE_MODEcopy or move
SOURCE_FILE_MTIMETARGET_FILE_MTIMESOURCE_FILE_CTIMETARGET_FILE_CTIMESOURCE_FILE_ATIMETARGET_FILE_ATIMESOURCE_FILE_SIZETARGET_FILE_SIZESome attributes of the source and target files to help the resolver. File time attributes are in unix timestamp, size is in bytes.
EXIT STATUS
If the conflict resolver programm return a non-zero exit status,
it is considered failure (and recorded if --faillog is given).
On zero exit status, the conflict resolution is get from the command's output's last line.
Don't write more than 1 newline char (\
) to the very end,
otherwise the last line would only contain the empty string.
SIGNALS
Conflict resolution signals,
ie. what the resolver programm can signal back to organizebydate(1) by its last STDOUT line.
Don't copy (move) source file, and don't do any processing (eg. don't move successfully copied source file).
Copy (move) source to target. Optionally with a new target path. This always (attempts to) overwrites the target even if --overwrite is not given, and either if NEW-TARGET is given or nor. So it's the resolver programm's responsibility to prevent unwanted overwrite.
Indicate that the source file is already there on the target path,
and no need to copy/move.
organizebydate(1) may still set the target's mtime (atime)
when --set-mtime (--set-atime) option is given;
and still moves the source file when --move-success-template is given.
Emit done signal if the same file is already present on the target location,
or the conflict resolver put it there,
with equal binary content to the source file.
Similar to done but explicitely fail the current item copy/move. This is recorded in fail log if --faillog option is given.
You may do extra steps in the conflict resolver's logic: eg. rename old target or move to an other directory and signal proceed at the end, or eg. remove source file and signal skip - this is useful in move mode.
If you want to ask the user interactively, don't read from stdin(3),
rather re-open the tty(4).
stdout(3) is buffered and then echoed except the last line.
stderr(3) is let through as-is.
Determining timestamps is based on the file's change-, modify-, or access-time. Default is mtime.
Files are raw Emails.
Determining timestamps is based on the Date header.
Files are JPEG images.
Determining timestamps is based on EXIF tags.
Fall back to file mtime (ctime, atime) if datetime info is not found in embedded metadata (RFC-822, Exif, ...)
Set the copied (moved) files' mtime (atime) to the datetime used in the template.
Save failed paths to FILE.
Verbose mode
Dry run. Do not copy (move) files.
Output what would be done in OPERATION TAB SOURCE TAB TARGET format.
Where OPERATION is one of:
for --copy, --move, and --handler operation modes respectively and the target does not exist.
when the target already exists (and neither --overwrite nor --conflict-resolver-* option is given).
when --overwrite is allowed.
when a --conflict-resolver-* option is given.
Output documentation in plain text, POD, or troff (for man(1)) formats.
Minimum directory level to traverse. Equivalent to find(1)'s -mindepth option.
Maximum directory level to traverse. Equivalent to find(1)'s -maxdepth option.
Exit 0 if all files processed successfully.
Exit 1 on parameter error.
Exit 2 if at least 1 file is failed.