filename.html 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352
  1. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
  2. "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
  3. <html>
  4. <head>
  5. <title>FileName and Directory tags</title>
  6. <link rel=stylesheet type='text/css' href='style.css' title='Style'>
  7. <style type="text/css">
  8. <!--
  9. .prog { padding: 0.5em; border: 1px solid gray; background: #fee }
  10. -->
  11. </style>
  12. </head>
  13. <body>
  14. <h2 class='up'>Writing "FileName" and "Directory" tags</h2>
  15. <p>By writing the <b>FileName</b> and/or <b>Directory</b> tags, ExifTool can be
  16. used to rename and/or move images into directories according to any information
  17. contained in the image. This is a powerful feature when combined with the
  18. <code>-tagsFromFile</code> ability to copy the values from other tags. The most
  19. common use of this feature is to organize images by date/time, but any other tag
  20. value may also be used.</p>
  21. <p>Writing the <b>Directory</b> tag moves a file to a specified directory. The
  22. directory is created if it doesn't already exist.</p>
  23. <p>Writing the <b>FileName</b> tag renames a file. If the new <b>FileName</b>
  24. has a directory specification (ie. contains a '<code>/</code>' character), then
  25. the file is also moved to the specified directory (see
  26. <a href="#ex6">example 6</a> below). Existing files will not be overwritten
  27. (but see "Warning" below).</p>
  28. <p>The write-only <b>TestName</b> tag provides a mechanism for dry-run testing
  29. of the rename feature. Writing <b>TestName</b> displays the old and new names
  30. without making any changes to the files. (Note that there is no corresponding
  31. test tag for <b>Directory</b>, but <b>TestName</b> supports a full path name
  32. just like <b>FileName</b>, so the directory may be tested as well.)</p>
  33. <p>The <code>%d</code>, <code>%f</code>, <code>%e</code> file name format codes
  34. may be used to represent the directory, name and extension of the original file
  35. when specifying <b>FileName</b> and <b>Directory</b> tags via the command-line
  36. interface. (In a similar way to the <code>-o</code>, <code>-w</code> and
  37. <code>-tagsFromFile</code> options.) Also, <code>%c</code> may be used to add a
  38. copy number to the output file name to avoid collisions with existing file
  39. names. Note that these codes must be escaped with an extra <code>%</code> if
  40. used within a date format string. Modifiers may also be used to change the
  41. default behaviour of these format codes. See the <code>-w</code> option in the
  42. <a href="exiftool_pod.html">application documentation</a> for details.</p>
  43. <p>When organizing files by date/time, use of the <code>-d</code> (date format)
  44. option is essential to specify a format for the filename (and/or directory
  45. name). The examples below demonstrate the use of this feature. Also, a list of
  46. of <a href="#codes">common date format codes</a> is provided for reference.</p>
  47. <blockquote class=prog><b class=red>Advanced feature:</b> The write-only
  48. <b>HardLink</b> tag may be written using a technique similar to <b>FileName</b>.
  49. Instead of renaming or moving the file, writing <b>HardLink</b> creates a hard
  50. link with the specified name. This feature allows files to be organized without
  51. affecting the originals. See the <a href="TagNames/extra.html">Extra Tags
  52. documentation</a> for more information.</blockquote>
  53. <h3>Notes:</h3>
  54. <p>Writing the <b>FileName</b> and/or <b>Directory</b> tags alone causes the
  55. file to be renamed or moved, not copied. However, if any "real" tags are
  56. written at the same time, then the file is rewritten to the new destination and
  57. the original file is left unchanged. (Only the four writable "pseudo" tags,
  58. <b>FileName</b>, <b>Directory</b>, <b>FileModifyDate</b> and
  59. <b>FileCreateDate</b>, may be set without causing the file to be rewritten.) If
  60. desired, the <code>-overwrite_original</code> option may be used to remove the
  61. original copy when the file is rewritten.</p>
  62. <p>Conversely, the <code>-o</code> option may be used to force exiftool to
  63. always create a copy of the file, even if no meta-information tags are written.
  64. This is true even if the <code>-o</code> option is superseded by writing the
  65. <b>Directory</b> tag, or through a <b>FileName</b> which includes a directory
  66. specification. (See <a href="#ex5">example 5</a> below. Also see
  67. <a href="#ex11">example 11</a> for the directory precedence rules.)</p>
  68. <p>If the <code>-d</code> option is used, the unformatted date/time value must
  69. be valid (ie. in the form "<code>YYYY:mm:dd HH:MM:SS</code>"), otherwise the
  70. date formatting will fail and the file will not be renamed or moved.</p>
  71. <p>In a Windows batch file, all <code>%</code> characters must be escaped as
  72. <code>%%</code>. This can result in extreme format codes like
  73. <code>%%%%f</code> when using the <code>-d</code> option.</p>
  74. <blockquote class=prog><b class=red>Warning:</b>
  75. Writing <b>illegal file names</b> in Windows can have unpredictable results and
  76. may result in <b>data loss</b>. Illegal characters in Windows file names are:
  77. <pre class=code> / \ ? * : | " &lt; &gt;</pre>
  78. Any tag used in generating a file name which may contain these characters must
  79. first be filtered to remove or translate these characters. A special feature
  80. allows these characters to be removed from a tag value by adding a semicolon
  81. inside the braces after a tag name. For example:
  82. <pre class=code> exiftool "-filename&lt;${model;}.%e" c:\images</pre>
  83. This advanced formatting feature may also be used to do arbitrary reformatting
  84. of any tag value used in a format string. See the <code>-p</code> option in the
  85. <a href="exiftool_pod.html">application documentation</a> for more details.
  86. </blockquote>
  87. <h2>Examples</h2>
  88. <a name="ex0"></a><table cellpadding=6>
  89. <tr><td valign='top'>&nbsp;0.</td><td bgcolor='#dddddd'><code class='blk'>
  90. exiftool -d %Y%m%d_%H%M%%-c.%%e "-testname&lt;CreateDate" DIR
  91. </code></td></tr></table>
  92. <blockquote>
  93. The <b>TestName</b> tag is used for dry-run testing of the file renaming
  94. feature. The above command is identical to that of the next example except that
  95. <b>TestName</b> is written instead of <b>FileName</b>. So instead of renaming
  96. the files, this command prints the old and new file names without actually
  97. changing anything. For example:
  98. <blockquote><pre>&gt; <span class=code>exiftool -d %Y%m%d_%H%M%%-c.%%e "-testname&lt;CreateDate" tmp</span>
  99. 'tmp/a.jpg' --&gt; 'tmp/20031031_1544.jpg'
  100. 'tmp/b.jpg' --&gt; 'tmp/20010519_1836.jpg'
  101. 1 directories scanned
  102. 0 image files updated
  103. 2 image files unchanged</pre></blockquote>
  104. </blockquote>
  105. <a name="ex1"></a><table cellpadding=6>
  106. <tr><td valign='top'>&nbsp;1.</td><td bgcolor='#dddddd'><code class='blk'>
  107. exiftool -d %Y%m%d_%H%M%%-c.%%e "-filename&lt;CreateDate" DIR
  108. </code></td></tr></table>
  109. <blockquote>
  110. Rename all images in directory '<code>DIR</code>' to names like
  111. '<code>20060327_1058-2.jpg</code>', with individual file names derived from the
  112. value of the CreateDate (plus a copy number with a leading '<code>-</code>' if a
  113. file with the same name already exists), and with the same extension as the
  114. original image. <i class=lt>[Note that copying tag values with '<code>&lt;</code>' implies
  115. '<code>-tagsfromfile @</code>' unless otherwise specified. See the
  116. <code>-tagsFromFile</code> description in the
  117. <a href="exiftool_pod.html">application documentation</a> for details.]</i>
  118. <p><b>FAQ:</b> <i>"Why doesn't this command rename my files?"</i></p>
  119. <p>There are 2 common reasons for this:</p>
  120. <p>a) When a directory name is specified, this command will only rename "writable"
  121. files in the directory. Use '<code>exiftool -listwf</code>' to list the
  122. extensions of currently writable file types. The <code>-ext</code> option may
  123. be used to rename other file types (eg. '<code>-ext avi</code>').</p>
  124. <p>b) For this command to work, the CreateDate tag must exist in the source
  125. file. Use '<code>exiftool -createdate FILE</code>' to see if a file contains
  126. this information. If it doesn't, you may need to use another date/time tag such
  127. as DateTimeOriginal or FileModifyDate. To see all available date/time tags in a
  128. file (and their locations), use '<code>exiftool -a -G1 -s -time:all FILE</code>'.</p>
  129. </blockquote>
  130. <a name="ex2"></a><table cellpadding=6>
  131. <tr><td valign='top'>&nbsp;2.</td><td bgcolor='#dddddd'><code class='blk'>
  132. exiftool -d %Y-%m-%d "-directory&lt;datetimeoriginal" image.jpg
  133. </code></td></tr></table>
  134. <blockquote>
  135. Move '<code>image.jpg</code>' into a directory with a name given by
  136. DateTimeOriginal, in the form '<code>2006-03-27</code>'.
  137. </blockquote>
  138. <a name="ex3"></a><table cellpadding=6>
  139. <tr><td valign='top'>&nbsp;3.</td><td bgcolor='#dddddd'><code class='blk'>
  140. exiftool '-filename&lt;%f_$imagesize.%e' dir
  141. </code></td></tr></table>
  142. <blockquote>
  143. This example uses an expression to add the image size to the name of all images
  144. in directory '<code>dir</code>'. For example, this would remame a 640x480 image
  145. called '<code>image.jpg</code>' to '<code>image_640x480.jpg</code>'. (Note that
  146. the single quotes are necessary in Unix shells due to the '<code>$</code>'
  147. symbol, but double quotes must be used instead when running in a Windows cmd shell.)
  148. </blockquote>
  149. <a name="ex4"></a><table cellpadding=6>
  150. <tr><td valign='top'>&nbsp;4.</td><td bgcolor='#dddddd'><code class='blk'>
  151. exiftool -r -directory=%e_images/%d pics
  152. </code></td></tr></table>
  153. <blockquote>
  154. Recursively move all images based in directory '<code>pics</code>' to
  155. separate directory trees organized by file extension. For instance, in this
  156. example the file '<code>pics/toys/new_car.jpg</code>' is moved to
  157. '<code>jpg_images/pics/toys/new_car.jpg</code>'.
  158. </blockquote>
  159. <a name="ex5"></a><table cellpadding=6>
  160. <tr><td valign='top'>&nbsp;5.</td><td bgcolor='#dddddd'><code class='blk'>
  161. exiftool -r -o %e_images/%d pics<br>
  162. exiftool -r -o dummy/ -directory=%e_images/%d pics
  163. </code></td></tr></table>
  164. <blockquote>
  165. Both of these commands have the same effect as example 3 above except that
  166. images are copied instead of moved since the <code>-o</code> option was used. In
  167. the second command the trailing '<code>/</code>' on '<code>dummy/</code>' is
  168. necessary because otherwise '<code>dummy</code>' would be interpreted as a file
  169. name. This technique of using <code>-o</code> with a dummy directory name is
  170. necessary when the directory name is derived from the value of other tags (eg.
  171. '<code>-directory&lt;createDate</code>') and you want the files to be copied
  172. instead of moved. (Because the values of other tags may not be used with the
  173. <code>-o</code> option.)
  174. </blockquote>
  175. <a name="ex6"></a><table cellpadding=6>
  176. <tr><td valign='top'>&nbsp;6.</td><td bgcolor='#dddddd'><code class='blk'>
  177. exiftool -r -d %Y/%m/%d/image_%H%M%S.%%e "-filename&lt;filemodifydate" DIR
  178. </code></td></tr></table>
  179. <blockquote>
  180. Recusively rename all images in '<code>DIR</code>' and any contained
  181. subdirectories to the form '<code>image_HHMMSS.EXT</code>' (where
  182. '<code>ext</code>' is the original file extension), and move them into a new
  183. directory hierarchy based on date of file modification, with path names like
  184. '<code>2006/03/27/image_105859.jpg</code>'.
  185. </blockquote>
  186. <p>The following examples demonstrate the interaction of this feature with
  187. other ExifTool options:</p>
  188. <a name="ex7"></a><table cellpadding=6>
  189. <tr><td valign='top'>&nbsp;7.</td><td bgcolor='#dddddd'><code class='blk'>
  190. exiftool -filename=new.jpg dir/image.jpg
  191. </code></td></tr></table>
  192. <blockquote>
  193. Rename '<code>dir/image.jpg</code>' to '<code>dir/new.jpg</code>'.
  194. </blockquote>
  195. <a name="ex8"></a><table cellpadding=6>
  196. <tr><td valign='top'>&nbsp;8.</td><td bgcolor='#dddddd'><code class='blk'>
  197. exiftool -filename=new.jpg -comment=xxx dir/image.jpg
  198. </code></td></tr></table>
  199. <blockquote>
  200. Copy '<code>dir/image.jpg</code>', add a new comment, and write output to
  201. '<code>dir/new.jpg</code>'. The original file '<code>dir/image.jpg</code>' is
  202. not changed.
  203. </blockquote>
  204. <a name="ex9"></a><table cellpadding=6>
  205. <tr><td valign='top'>&nbsp;9.</td><td bgcolor='#dddddd'><code class='blk'>
  206. exiftool -filename=new.jpg -comment=xxx -overwrite_original dir/image.jpg
  207. </code></td></tr></table>
  208. <blockquote>
  209. Rewrite '<code>dir/image.jpg</code>', adding a new comment and writing output to
  210. '<code>dir/new.jpg</code>'. The original file '<code>dir/image.jpg</code>' is
  211. removed.
  212. </blockquote>
  213. <a name="ex10"></a><table cellpadding=6>
  214. <tr><td valign='top'>10.</td><td bgcolor='#dddddd'><code class='blk'>
  215. exiftool -o tmp/ -filename=new.jpg image.jpg<br>
  216. exiftool -o tmp/xxx.jpg -filename=new.jpg image.jpg<br>
  217. exiftool -o tmp/new.jpg image.jpg
  218. </code></td></tr></table>
  219. <blockquote>
  220. A file name or directory specified via the <b>FileName</b> or <b>Directory</b>
  221. tag takes precedence over that specified by the <code>-o</code> option, so these
  222. three commands all have the same effect: '<code>tmp/new.jpg</code>' is created
  223. without changing '<code>image.jpg</code>'. Note that in the first command, the
  224. trailing '<code>/</code>' on '<code>tmp/</code>' is necessary if the
  225. '<code>tmp</code>' directory doesn't already exist, otherwise '<code>tmp</code>'
  226. would be taken as a file name and '<code>new.jpg</code>' would be created in the
  227. current directory. As illustrated in example 4 above, the file is rewritten
  228. instead of simply being renamed when the '<code>-o</code>' option is used.
  229. </blockquote>
  230. <a name="ex11"></a><table cellpadding=6>
  231. <tr><td valign='top'>11.</td><td bgcolor='#dddddd'><code class='blk'>
  232. exiftool -directory=dir1 -filename=dir2/out.jpg -o dir3/ dir4/image.jpg
  233. </code></td></tr></table>
  234. <blockquote>
  235. This example demonstrates the priorities of directory names specified using
  236. different techniques. The output directory is taken from the first directory
  237. specified from the following list: 1) the <b>Directory</b> tag, 2) the
  238. directory part of the <b>FileName</b> tag, 3) the directory part of the
  239. <code>-o</code> option, or 4) the source directory, in that order. The order of
  240. the arguments on the command line is not significant. In this example, the
  241. target file is copied (not moved, because the <code>-o</code> option was used)
  242. to '<code>dir1/image.jpg</code>'. </blockquote>
  243. <blockquote>Note that both the <b>FileName</b> tag and the <code>-o</code>
  244. option may be used without a directory specification, in which case the
  245. directory with the next highest priority is used. Also note that if
  246. <code>-o</code> specifies a directory, then the directory name must end with a
  247. '<code>/</code>' or the directory must already exist, otherwise ExifTool will
  248. interpret the last part as a file name. (eg. '<code>-o images/test</code>'
  249. specifies the '<code>images</code>' directory unless the
  250. '<code>images/test</code>' directory already exists, while '<code>-o
  251. images/test/</code>' unabiguously specifies the '<code>images/test</code>'
  252. directory.)
  253. </blockquote>
  254. <a name="ex12"></a><table cellpadding=6>
  255. <tr><td valign='top'>12.</td><td bgcolor='#dddddd'><code class='blk'>
  256. exiftool -d %Y/%m "-directory&lt;filemodifydate" "-directory&lt;createdate" "-directory&lt;datetimeoriginal" .
  257. </code></td></tr></table>
  258. <blockquote>Move image files from the current directory (<code>.</code>) into a
  259. directory hierarcy based on year/month. In this command the Directory tag is
  260. set from multiple other date/time tags. ExifTool evaluates the command-line
  261. arguments left to right, and latter assignments to the same tag override earlier
  262. ones, so the Directory for each image is ultimately set by the rightmost copy
  263. argument that is valid for that image. Specifically, Directory is set from
  264. DateTimeOriginal if it exists, otherwise CreateDate if it exists, and finally
  265. FileModifyDate (which always exists) is used as a fallback.</blockquote>
  266. <a name="codes"></a><h2>Common Date Format Codes</h2>
  267. <p>Date format codes are used in the argument to the <code>-d</code> option to
  268. represent components of the date/time string. The codes listed below are common
  269. to most systems, but additional codes may be available on your specific system
  270. -- see your <i>strftime</i> man page for details.</p>
  271. <blockquote><table>
  272. <tr><th>%a</th><td>- abbreviated locale weekday name</td></tr>
  273. <tr><th>%A</th><td>- full locale weekday name</td></tr>
  274. <tr><th>%b</th><td>- abbreviated locale month name</td></tr>
  275. <tr><th>%B</th><td>- full locale month name</td></tr>
  276. <tr><th>%c</th><td>- preferred locale date/time representation</td></tr>
  277. <tr><th>%d</th><td>- day of month (01-31)</td></tr>
  278. <tr><th>%H</th><td>- hour on a 24-hour clock (00-23)</td></tr>
  279. <tr><th>%I</th><td>- hour on a 12-hour clock (01-12)</td></tr>
  280. <tr><th>%j</th><td>- day of year (001-366)</td></tr>
  281. <tr><th>%m</th><td>- month number (01-12)</td></tr>
  282. <tr><th>%M</th><td>- minute (00-59)</td></tr>
  283. <tr><th>%p</th><td>- 'AM' or 'PM'</td></tr>
  284. <tr><th>%s</th><td>- number of seconds since the Epoch, UTC (see note 1 below)</td></tr>
  285. <tr><th>%S</th><td>- seconds (00-59)</td></tr>
  286. <tr><th>%w</th><td>- weekday number (0-6)</td></tr>
  287. <tr><th>%W</th><td>- week number of the year (00-53)</td></tr>
  288. <tr><th>%x</th><td>- preferred locale date representation</td></tr>
  289. <tr><th>%X</th><td>- preferred locale time representation</td></tr>
  290. <tr><th>%y</th><td>- 2-digit year (00-99)</td></tr>
  291. <tr><th>%Y</th><td>- 4-digit year (eg. 2006)</td></tr>
  292. <tr><th>%z</th><td>- time zone in the form +/-hhmm (see note 1 below)</td></tr>
  293. <tr><th>%Z</th><td>- system time zone name (see note 2 below)</td></tr>
  294. <tr><th>%%</th><td>- a literal '%' character</td></tr>
  295. </table></blockquote>
  296. <p>ExifTool file name format codes may be used inside a date format
  297. string when a date/time tag is used to set the value of the <b>FileName</b> or
  298. <b>Directory</b> tags via the command-line interface. In this case, an extra
  299. '<code>%</code>' must be added to pass the format code through the date/time
  300. parser:</p>
  301. <blockquote><table>
  302. <tr><th>%%d</th><td>- original file directory (including trailing "/" if necessary)</td></tr>
  303. <tr><th>%%f</th><td>- original file name (without the extension)</td></tr>
  304. <tr><th>%%e</th><td>- original file extension (not including the ".")</td></tr>
  305. <tr><th>%%c</th><td>- copy number (output files only)</td></tr>
  306. </table></blockquote>
  307. <p>See the <code>-w</code> option in the <a href="exiftool_pod.html">exiftool
  308. application documentation</a> for details about special features available
  309. with these name format codes.</p>
  310. <p><b>Notes:</b></p>
  311. <ol>
  312. <li>The %s and %z format codes use the time zone specified by the date/time
  313. value. If the date/time value does not include a time zone specification, then
  314. it is interpreted as a local time in the system time zone. These format codes
  315. are parsed by ExifTool, so they should work on all systems.<br><br></li>
  316. <li>The %Z format code ignores any time zone specified in the date/time value,
  317. and returns the system time-zone name for the given date/time interpreted as a
  318. local system time.</li>
  319. </ol>
  320. <hr>
  321. <p class='lf'><a href="index.html">&lt;-- Back to ExifTool home page</a></p>
  322. </body>
  323. </html>