123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352 |
- <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
- "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
- <html>
- <head>
- <title>FileName and Directory tags</title>
- <link rel=stylesheet type='text/css' href='style.css' title='Style'>
- <style type="text/css">
- <!--
- .prog { padding: 0.5em; border: 1px solid gray; background: #fee }
- -->
- </style>
- </head>
- <body>
- <h2 class='up'>Writing "FileName" and "Directory" tags</h2>
- <p>By writing the <b>FileName</b> and/or <b>Directory</b> tags, ExifTool can be
- used to rename and/or move images into directories according to any information
- contained in the image. This is a powerful feature when combined with the
- <code>-tagsFromFile</code> ability to copy the values from other tags. The most
- common use of this feature is to organize images by date/time, but any other tag
- value may also be used.</p>
- <p>Writing the <b>Directory</b> tag moves a file to a specified directory. The
- directory is created if it doesn't already exist.</p>
- <p>Writing the <b>FileName</b> tag renames a file. If the new <b>FileName</b>
- has a directory specification (ie. contains a '<code>/</code>' character), then
- the file is also moved to the specified directory (see
- <a href="#ex6">example 6</a> below). Existing files will not be overwritten
- (but see "Warning" below).</p>
- <p>The write-only <b>TestName</b> tag provides a mechanism for dry-run testing
- of the rename feature. Writing <b>TestName</b> displays the old and new names
- without making any changes to the files. (Note that there is no corresponding
- test tag for <b>Directory</b>, but <b>TestName</b> supports a full path name
- just like <b>FileName</b>, so the directory may be tested as well.)</p>
- <p>The <code>%d</code>, <code>%f</code>, <code>%e</code> file name format codes
- may be used to represent the directory, name and extension of the original file
- when specifying <b>FileName</b> and <b>Directory</b> tags via the command-line
- interface. (In a similar way to the <code>-o</code>, <code>-w</code> and
- <code>-tagsFromFile</code> options.) Also, <code>%c</code> may be used to add a
- copy number to the output file name to avoid collisions with existing file
- names. Note that these codes must be escaped with an extra <code>%</code> if
- used within a date format string. Modifiers may also be used to change the
- default behaviour of these format codes. See the <code>-w</code> option in the
- <a href="exiftool_pod.html">application documentation</a> for details.</p>
- <p>When organizing files by date/time, use of the <code>-d</code> (date format)
- option is essential to specify a format for the filename (and/or directory
- name). The examples below demonstrate the use of this feature. Also, a list of
- of <a href="#codes">common date format codes</a> is provided for reference.</p>
- <blockquote class=prog><b class=red>Advanced feature:</b> The write-only
- <b>HardLink</b> tag may be written using a technique similar to <b>FileName</b>.
- Instead of renaming or moving the file, writing <b>HardLink</b> creates a hard
- link with the specified name. This feature allows files to be organized without
- affecting the originals. See the <a href="TagNames/extra.html">Extra Tags
- documentation</a> for more information.</blockquote>
- <h3>Notes:</h3>
- <p>Writing the <b>FileName</b> and/or <b>Directory</b> tags alone causes the
- file to be renamed or moved, not copied. However, if any "real" tags are
- written at the same time, then the file is rewritten to the new destination and
- the original file is left unchanged. (Only the four writable "pseudo" tags,
- <b>FileName</b>, <b>Directory</b>, <b>FileModifyDate</b> and
- <b>FileCreateDate</b>, may be set without causing the file to be rewritten.) If
- desired, the <code>-overwrite_original</code> option may be used to remove the
- original copy when the file is rewritten.</p>
- <p>Conversely, the <code>-o</code> option may be used to force exiftool to
- always create a copy of the file, even if no meta-information tags are written.
- This is true even if the <code>-o</code> option is superseded by writing the
- <b>Directory</b> tag, or through a <b>FileName</b> which includes a directory
- specification. (See <a href="#ex5">example 5</a> below. Also see
- <a href="#ex11">example 11</a> for the directory precedence rules.)</p>
- <p>If the <code>-d</code> option is used, the unformatted date/time value must
- be valid (ie. in the form "<code>YYYY:mm:dd HH:MM:SS</code>"), otherwise the
- date formatting will fail and the file will not be renamed or moved.</p>
- <p>In a Windows batch file, all <code>%</code> characters must be escaped as
- <code>%%</code>. This can result in extreme format codes like
- <code>%%%%f</code> when using the <code>-d</code> option.</p>
- <blockquote class=prog><b class=red>Warning:</b>
- Writing <b>illegal file names</b> in Windows can have unpredictable results and
- may result in <b>data loss</b>. Illegal characters in Windows file names are:
- <pre class=code> / \ ? * : | " < ></pre>
- Any tag used in generating a file name which may contain these characters must
- first be filtered to remove or translate these characters. A special feature
- allows these characters to be removed from a tag value by adding a semicolon
- inside the braces after a tag name. For example:
- <pre class=code> exiftool "-filename<${model;}.%e" c:\images</pre>
- This advanced formatting feature may also be used to do arbitrary reformatting
- of any tag value used in a format string. See the <code>-p</code> option in the
- <a href="exiftool_pod.html">application documentation</a> for more details.
- </blockquote>
- <h2>Examples</h2>
- <a name="ex0"></a><table cellpadding=6>
- <tr><td valign='top'> 0.</td><td bgcolor='#dddddd'><code class='blk'>
- exiftool -d %Y%m%d_%H%M%%-c.%%e "-testname<CreateDate" DIR
- </code></td></tr></table>
- <blockquote>
- The <b>TestName</b> tag is used for dry-run testing of the file renaming
- feature. The above command is identical to that of the next example except that
- <b>TestName</b> is written instead of <b>FileName</b>. So instead of renaming
- the files, this command prints the old and new file names without actually
- changing anything. For example:
- <blockquote><pre>> <span class=code>exiftool -d %Y%m%d_%H%M%%-c.%%e "-testname<CreateDate" tmp</span>
- 'tmp/a.jpg' --> 'tmp/20031031_1544.jpg'
- 'tmp/b.jpg' --> 'tmp/20010519_1836.jpg'
- 1 directories scanned
- 0 image files updated
- 2 image files unchanged</pre></blockquote>
- </blockquote>
- <a name="ex1"></a><table cellpadding=6>
- <tr><td valign='top'> 1.</td><td bgcolor='#dddddd'><code class='blk'>
- exiftool -d %Y%m%d_%H%M%%-c.%%e "-filename<CreateDate" DIR
- </code></td></tr></table>
- <blockquote>
- Rename all images in directory '<code>DIR</code>' to names like
- '<code>20060327_1058-2.jpg</code>', with individual file names derived from the
- value of the CreateDate (plus a copy number with a leading '<code>-</code>' if a
- file with the same name already exists), and with the same extension as the
- original image. <i class=lt>[Note that copying tag values with '<code><</code>' implies
- '<code>-tagsfromfile @</code>' unless otherwise specified. See the
- <code>-tagsFromFile</code> description in the
- <a href="exiftool_pod.html">application documentation</a> for details.]</i>
- <p><b>FAQ:</b> <i>"Why doesn't this command rename my files?"</i></p>
- <p>There are 2 common reasons for this:</p>
- <p>a) When a directory name is specified, this command will only rename "writable"
- files in the directory. Use '<code>exiftool -listwf</code>' to list the
- extensions of currently writable file types. The <code>-ext</code> option may
- be used to rename other file types (eg. '<code>-ext avi</code>').</p>
- <p>b) For this command to work, the CreateDate tag must exist in the source
- file. Use '<code>exiftool -createdate FILE</code>' to see if a file contains
- this information. If it doesn't, you may need to use another date/time tag such
- as DateTimeOriginal or FileModifyDate. To see all available date/time tags in a
- file (and their locations), use '<code>exiftool -a -G1 -s -time:all FILE</code>'.</p>
- </blockquote>
- <a name="ex2"></a><table cellpadding=6>
- <tr><td valign='top'> 2.</td><td bgcolor='#dddddd'><code class='blk'>
- exiftool -d %Y-%m-%d "-directory<datetimeoriginal" image.jpg
- </code></td></tr></table>
- <blockquote>
- Move '<code>image.jpg</code>' into a directory with a name given by
- DateTimeOriginal, in the form '<code>2006-03-27</code>'.
- </blockquote>
- <a name="ex3"></a><table cellpadding=6>
- <tr><td valign='top'> 3.</td><td bgcolor='#dddddd'><code class='blk'>
- exiftool '-filename<%f_$imagesize.%e' dir
- </code></td></tr></table>
- <blockquote>
- This example uses an expression to add the image size to the name of all images
- in directory '<code>dir</code>'. For example, this would remame a 640x480 image
- called '<code>image.jpg</code>' to '<code>image_640x480.jpg</code>'. (Note that
- the single quotes are necessary in Unix shells due to the '<code>$</code>'
- symbol, but double quotes must be used instead when running in a Windows cmd shell.)
- </blockquote>
- <a name="ex4"></a><table cellpadding=6>
- <tr><td valign='top'> 4.</td><td bgcolor='#dddddd'><code class='blk'>
- exiftool -r -directory=%e_images/%d pics
- </code></td></tr></table>
- <blockquote>
- Recursively move all images based in directory '<code>pics</code>' to
- separate directory trees organized by file extension. For instance, in this
- example the file '<code>pics/toys/new_car.jpg</code>' is moved to
- '<code>jpg_images/pics/toys/new_car.jpg</code>'.
- </blockquote>
- <a name="ex5"></a><table cellpadding=6>
- <tr><td valign='top'> 5.</td><td bgcolor='#dddddd'><code class='blk'>
- exiftool -r -o %e_images/%d pics<br>
- exiftool -r -o dummy/ -directory=%e_images/%d pics
- </code></td></tr></table>
- <blockquote>
- Both of these commands have the same effect as example 3 above except that
- images are copied instead of moved since the <code>-o</code> option was used. In
- the second command the trailing '<code>/</code>' on '<code>dummy/</code>' is
- necessary because otherwise '<code>dummy</code>' would be interpreted as a file
- name. This technique of using <code>-o</code> with a dummy directory name is
- necessary when the directory name is derived from the value of other tags (eg.
- '<code>-directory<createDate</code>') and you want the files to be copied
- instead of moved. (Because the values of other tags may not be used with the
- <code>-o</code> option.)
- </blockquote>
- <a name="ex6"></a><table cellpadding=6>
- <tr><td valign='top'> 6.</td><td bgcolor='#dddddd'><code class='blk'>
- exiftool -r -d %Y/%m/%d/image_%H%M%S.%%e "-filename<filemodifydate" DIR
- </code></td></tr></table>
- <blockquote>
- Recusively rename all images in '<code>DIR</code>' and any contained
- subdirectories to the form '<code>image_HHMMSS.EXT</code>' (where
- '<code>ext</code>' is the original file extension), and move them into a new
- directory hierarchy based on date of file modification, with path names like
- '<code>2006/03/27/image_105859.jpg</code>'.
- </blockquote>
- <p>The following examples demonstrate the interaction of this feature with
- other ExifTool options:</p>
- <a name="ex7"></a><table cellpadding=6>
- <tr><td valign='top'> 7.</td><td bgcolor='#dddddd'><code class='blk'>
- exiftool -filename=new.jpg dir/image.jpg
- </code></td></tr></table>
- <blockquote>
- Rename '<code>dir/image.jpg</code>' to '<code>dir/new.jpg</code>'.
- </blockquote>
- <a name="ex8"></a><table cellpadding=6>
- <tr><td valign='top'> 8.</td><td bgcolor='#dddddd'><code class='blk'>
- exiftool -filename=new.jpg -comment=xxx dir/image.jpg
- </code></td></tr></table>
- <blockquote>
- Copy '<code>dir/image.jpg</code>', add a new comment, and write output to
- '<code>dir/new.jpg</code>'. The original file '<code>dir/image.jpg</code>' is
- not changed.
- </blockquote>
- <a name="ex9"></a><table cellpadding=6>
- <tr><td valign='top'> 9.</td><td bgcolor='#dddddd'><code class='blk'>
- exiftool -filename=new.jpg -comment=xxx -overwrite_original dir/image.jpg
- </code></td></tr></table>
- <blockquote>
- Rewrite '<code>dir/image.jpg</code>', adding a new comment and writing output to
- '<code>dir/new.jpg</code>'. The original file '<code>dir/image.jpg</code>' is
- removed.
- </blockquote>
- <a name="ex10"></a><table cellpadding=6>
- <tr><td valign='top'>10.</td><td bgcolor='#dddddd'><code class='blk'>
- exiftool -o tmp/ -filename=new.jpg image.jpg<br>
- exiftool -o tmp/xxx.jpg -filename=new.jpg image.jpg<br>
- exiftool -o tmp/new.jpg image.jpg
- </code></td></tr></table>
- <blockquote>
- A file name or directory specified via the <b>FileName</b> or <b>Directory</b>
- tag takes precedence over that specified by the <code>-o</code> option, so these
- three commands all have the same effect: '<code>tmp/new.jpg</code>' is created
- without changing '<code>image.jpg</code>'. Note that in the first command, the
- trailing '<code>/</code>' on '<code>tmp/</code>' is necessary if the
- '<code>tmp</code>' directory doesn't already exist, otherwise '<code>tmp</code>'
- would be taken as a file name and '<code>new.jpg</code>' would be created in the
- current directory. As illustrated in example 4 above, the file is rewritten
- instead of simply being renamed when the '<code>-o</code>' option is used.
- </blockquote>
- <a name="ex11"></a><table cellpadding=6>
- <tr><td valign='top'>11.</td><td bgcolor='#dddddd'><code class='blk'>
- exiftool -directory=dir1 -filename=dir2/out.jpg -o dir3/ dir4/image.jpg
- </code></td></tr></table>
- <blockquote>
- This example demonstrates the priorities of directory names specified using
- different techniques. The output directory is taken from the first directory
- specified from the following list: 1) the <b>Directory</b> tag, 2) the
- directory part of the <b>FileName</b> tag, 3) the directory part of the
- <code>-o</code> option, or 4) the source directory, in that order. The order of
- the arguments on the command line is not significant. In this example, the
- target file is copied (not moved, because the <code>-o</code> option was used)
- to '<code>dir1/image.jpg</code>'. </blockquote>
- <blockquote>Note that both the <b>FileName</b> tag and the <code>-o</code>
- option may be used without a directory specification, in which case the
- directory with the next highest priority is used. Also note that if
- <code>-o</code> specifies a directory, then the directory name must end with a
- '<code>/</code>' or the directory must already exist, otherwise ExifTool will
- interpret the last part as a file name. (eg. '<code>-o images/test</code>'
- specifies the '<code>images</code>' directory unless the
- '<code>images/test</code>' directory already exists, while '<code>-o
- images/test/</code>' unabiguously specifies the '<code>images/test</code>'
- directory.)
- </blockquote>
- <a name="ex12"></a><table cellpadding=6>
- <tr><td valign='top'>12.</td><td bgcolor='#dddddd'><code class='blk'>
- exiftool -d %Y/%m "-directory<filemodifydate" "-directory<createdate" "-directory<datetimeoriginal" .
- </code></td></tr></table>
- <blockquote>Move image files from the current directory (<code>.</code>) into a
- directory hierarcy based on year/month. In this command the Directory tag is
- set from multiple other date/time tags. ExifTool evaluates the command-line
- arguments left to right, and latter assignments to the same tag override earlier
- ones, so the Directory for each image is ultimately set by the rightmost copy
- argument that is valid for that image. Specifically, Directory is set from
- DateTimeOriginal if it exists, otherwise CreateDate if it exists, and finally
- FileModifyDate (which always exists) is used as a fallback.</blockquote>
- <a name="codes"></a><h2>Common Date Format Codes</h2>
- <p>Date format codes are used in the argument to the <code>-d</code> option to
- represent components of the date/time string. The codes listed below are common
- to most systems, but additional codes may be available on your specific system
- -- see your <i>strftime</i> man page for details.</p>
- <blockquote><table>
- <tr><th>%a</th><td>- abbreviated locale weekday name</td></tr>
- <tr><th>%A</th><td>- full locale weekday name</td></tr>
- <tr><th>%b</th><td>- abbreviated locale month name</td></tr>
- <tr><th>%B</th><td>- full locale month name</td></tr>
- <tr><th>%c</th><td>- preferred locale date/time representation</td></tr>
- <tr><th>%d</th><td>- day of month (01-31)</td></tr>
- <tr><th>%H</th><td>- hour on a 24-hour clock (00-23)</td></tr>
- <tr><th>%I</th><td>- hour on a 12-hour clock (01-12)</td></tr>
- <tr><th>%j</th><td>- day of year (001-366)</td></tr>
- <tr><th>%m</th><td>- month number (01-12)</td></tr>
- <tr><th>%M</th><td>- minute (00-59)</td></tr>
- <tr><th>%p</th><td>- 'AM' or 'PM'</td></tr>
- <tr><th>%s</th><td>- number of seconds since the Epoch, UTC (see note 1 below)</td></tr>
- <tr><th>%S</th><td>- seconds (00-59)</td></tr>
- <tr><th>%w</th><td>- weekday number (0-6)</td></tr>
- <tr><th>%W</th><td>- week number of the year (00-53)</td></tr>
- <tr><th>%x</th><td>- preferred locale date representation</td></tr>
- <tr><th>%X</th><td>- preferred locale time representation</td></tr>
- <tr><th>%y</th><td>- 2-digit year (00-99)</td></tr>
- <tr><th>%Y</th><td>- 4-digit year (eg. 2006)</td></tr>
- <tr><th>%z</th><td>- time zone in the form +/-hhmm (see note 1 below)</td></tr>
- <tr><th>%Z</th><td>- system time zone name (see note 2 below)</td></tr>
- <tr><th>%%</th><td>- a literal '%' character</td></tr>
- </table></blockquote>
- <p>ExifTool file name format codes may be used inside a date format
- string when a date/time tag is used to set the value of the <b>FileName</b> or
- <b>Directory</b> tags via the command-line interface. In this case, an extra
- '<code>%</code>' must be added to pass the format code through the date/time
- parser:</p>
- <blockquote><table>
- <tr><th>%%d</th><td>- original file directory (including trailing "/" if necessary)</td></tr>
- <tr><th>%%f</th><td>- original file name (without the extension)</td></tr>
- <tr><th>%%e</th><td>- original file extension (not including the ".")</td></tr>
- <tr><th>%%c</th><td>- copy number (output files only)</td></tr>
- </table></blockquote>
- <p>See the <code>-w</code> option in the <a href="exiftool_pod.html">exiftool
- application documentation</a> for details about special features available
- with these name format codes.</p>
- <p><b>Notes:</b></p>
- <ol>
- <li>The %s and %z format codes use the time zone specified by the date/time
- value. If the date/time value does not include a time zone specification, then
- it is interpreted as a local time in the system time zone. These format codes
- are parsed by ExifTool, so they should work on all systems.<br><br></li>
- <li>The %Z format code ignores any time zone specified in the date/time value,
- and returns the system time-zone name for the given date/time interpreted as a
- local system time.</li>
- </ol>
- <hr>
- <p class='lf'><a href="index.html"><-- Back to ExifTool home page</a></p>
- </body>
- </html>
|