[datetree logo]


 Intro   Manual   See It   Get It 

1. Introduction
2. Shareware information
3. Basics
4. Folder Organization
5. Starting DateTree
6. Being selective about which files to copy
7. Copying entire folders
8. Advanced patterns (Regular expressions)
9. Acknowledgments

1. Introduction
DateTree is a program which will help you to organize files by date. I wrote this program to organize my digital photos, but you can use DateTree to organize files of any type – or even of many types – into a collection of folders named by date.

You simply choose a folder into which you want to copy files (My Photos, in the screen shot at right). DateTree will create subfolders inside that folder named for the dates of the files to be copied, then copies away. By default, for jpeg and tiff files (popular digital camera formats), DateTree uses the date encoded into the photo by your digital camera. If a date can't be found in a file, then DateTree uses the date the file was last modified.

Several date formats are available in the application, and you can have DateTree be selective in which files to copy. Once you specify the folder to copy from, DateTree generally copies all the files it can find under that folder, but you can teach DateTree about folders that should be preserved (like folders containing panoramas for example).

DateTree works by copying files – never by moving them – so you never have to worry that your files will get deleted. A comprehensive report of files copied, skipped and any errors is presented each time you use DateTree.

2. Shareware Information

This program is shareware. That means you get to try it out to see if you like it before you buy it! You can try this program ten times, or for ten days, whichever is longer. After that time you have to register it if you want to keep on using it. Registration is only $6.99 (U.S. funds) and supports this product and other software products.

A registered copy can be installed on as many machines as you like, but each person using the program needs to register their own copy. Authoritative information on the shareware license can be read by choosing "Read License..." from the DateTree menu.

The Kagi online store sells the registrations; they have been around since 1994 and have a great reputation with both vendors and customers for security and quality service. You can register by choosing Register from the DateTree menu. You'll immediately receive a registration code by email.

Even a small utility like DateTree takes weeks of work to make it error-free, easy to use and attractive. Shareware works on the honor system, and I really appreciate your contribution to my software. Please register DateTree.

Contact Colin <datetree@juicer.orange-carb.org> for site licensing arrangements.

3. Basics
Before running DateTree for the first time, you should create a folder which will store your organized files. Use the Finder to create this folder. In this example I'm calling the folder My Photos, but you can call it whatever you'd like. You'll use DateTree to create the dated subfolders within this folder.

Once you've created the folder, start DateTree.

There are three main parts of the window. The upper right of the window (Organize Into:) is for specifying the folder which stores your organized files. DateTree will create its date folders directly inside this folder. You can either drag a file into the well (indented box), or press the Select... button to choose the folder. In the example (see right) I've already chosen the My Photos folder. (Unless you specify otherwise in the preferences, DateTree will remember the folders you last used in subsequent runs of the application).

The upper left of the window (Copy From:) is for specifying the files and folders you want to copy into your organized folder. In the example I have not yet selected this. The only practical difference in selection for this side of the window is that multiple files and folders can be selected (drag in a multiple selection, or choose multiple files using the Select... button). In addition, the right side of the window only accepts folders, while the left side accepts files and folders.

The lower portion of the window contains a progress meter which tracks the progress of file copying. When you press the Organize button, the file copying begins.

You can have as many organized folders on the system as you'd like (e.g. separate ones for photos and movies). Each time you run DateTree be sure that the Organize Into folder is set correctly.

After the file copying is complete a report window opens, displaying the number of files copied, which files may have been skipped (see the section on skipping below) and any errors that might have occurred during copying. Be sure to carefully review the report before deleting your original files, especially any errors that may have occurred. In particular, DateTree does not overwrite existing files, so it will not put two files with the same name into a date folder; the first one in will succeed, and the other will be reported in the error section.

Since DateTree copies your files (rather than moving them) you can (and should) verify that the copying has been done correctly and to your specifications before discarding the originals.

4. Folder Organization
Many people are happy with DateTree's default organization of their files. In this organization you specify the Organize Into folder, and DateTree creates a single set of folders immediately inside your Organize Into folder. For example, a file created on October 19, 2003 would be copied into a folder called "2003-10-19" inside the Organize Into folder. The exact naming scheme is selectable.

Some people find that over many years this results in a list of folders which is too long. They would prefer more organization in the list. This can be specified in the folder organization tab of the preferences. The default (described above) is called single-level organization because there is only one set of subfolders created under the Organize Into folder. There is also double-level and triple-level, which are described below.

Those who would prefer to have DateTree create a folder for the year, and then create dated subfolders within the year should select the double-level organization. In this organization the above file would result in the creation of a folder called "2003" in the Organize Into folder. Within the 2003 folder, an "October 19" folder is created, and the file placed inside. With this scheme, the first level subfolder is always named for the year, while the second level subfolder's naming scheme is selectable by you.

The double-level organization also offers options for those who want to store their files by month rather than by day. In these options, all files taken in, say October 2003, are stored directly in an October folder in a 2003 folder. No folders are created for the day of October. To select these formats choose an option below the Create one folder per month line. Note that the numbered options displayed in this section are the month number (10 indicates the tenth month, October, not the 10th of a month).

Those who like a very organized structure, or who have a large number of files to organize, may want a triple-level organization. In this scheme a year folder is created, a month folder within it, then a folder for the day within the month folder. In our example, a "2003" folder is created, and an "October" folder within it. Then, a folder called "19" is created within the October folder, and the file is copied into the 19 folder. In this organization you can specify the formats of the month folder (numeric, full name or abbreviated name) and the day folder (number, or number and day of the week).

For convenience and clarity, a preview shows you what a finder window would look like with your current selection of level and format. Note that because the finder sorts alphabetically, formats with textual month names (e.g. October instead of 10) will not appear in order in the finder. The format options list the path that will be created, with slash separating enclosing folders from their enclosed contents. The triple-level example above is shown as 2003/October/19 meaning a 19 folder inside an October folder inside a 2003 folder inside your Organize Into folder.

A note about changing your mind: you may start out with one folder organization and later change your mind about which to use. A simple way to reorganize your files is to create a new Organize Into folder, change your folder organization preferences, then use DateTree to organize from your old set of folders into the new one.

I've tried to strike a balance between too many and too few possible formats and organizations, with a slant towards more flexibility. If there's an option you'd like that I've left out, feel free to contact me at datetree@juicer.orange-carb.org. I can't promise to include every format (for obvious reasons) but I'll try to add any popular ones I've missed as future revisions come out.

5. Starting DateTree
DateTree tries to help you by making it easy to get your files through DateTree into your organized folders.

  • DateTree remembers the last folder you organized to. If you are copying from a single folder, DateTree will remember that for the next run as well. This can really speed things up if your digital camera always appears with the same name when it is connected.
  • The file menu contains a submenu with recently used Copy From folders
  • You can drop any file(s) or folder(s) on the DateTree application in your dock or in a Finder window. If DateTree is not running it will be started, pre-selecting those files in the Copy From section. If DateTree is already running this will re-select the files for you (just like dropping them on the well). This can speed things up quite a bit.
  • You can teach Mac OS X to launch DateTree automatically when you connect your digital camera. This configuration needs to be done in the preferences of the ImageCapture application which you will find in your Applications folder. Launch ImageCapture and access its preferences.
    • Mac OS X 10.1: Select Other... from the pop up list labeled Hot Plug Action: then select the DateTree application.
    • Mac OS X 10.2 and 10.3: Select Other... from the pop up list labeled When a camera is connected, open: then select the DateTree application.
    • If your supported operating system isn't listed here, and these instructions don't work, check for updated DateTree documentation online at http://www.orange-carb.org/DateTree

6. Being selective about which files to copy
DateTree tries very hard to find all the files inside the folders you specify on the Copy From side of the main window. It will open any folder it encounters and look inside for files (and other folders which will be searched in turn). Sometimes you may not want to copy all of these files. You may, for example, want to exclude files of some types, or you might only want to copy files of a certain type.

DateTree offers controls in the preferences panel which allow you to select exactly the files you want to copy (see right).

In this example DateTree is configured to copy every file it can under the Copy From folders, but in order for a file to be copied it must match one of the patterns provided. Each file, as it is encountered is compared to the patterns. If one of the patterns resembles the name of the file then it is copied, otherwise it is skipped. (Any skipped files are detailed in the report after copying, which is a great way to make sure your patterns are doing what you want.)

To add a new pattern to the list you press the Add button. To remove a pattern you simply click on it to select it, then click the Delete button. To edit a pattern double-click on it and it will become editable.

Patterns are created in a very simple format. An asterisk (*) character matches at least one other character, while a question mark (?) character matches exactly one other character. All other characters must match exactly, except that upper case and lower case versions of the same letter are considered to be the same. Patterns are matched against the names of files only, without any of their folder or path information. (A summary of this information is available within DateTree on a help panel accessible by pressing the question mark button next to the delete button.)

Here is how to interpret the specific patterns in the example:

  • *.jpg – This pattern will match any sequence of characters which end with ".jpg". So the file violin.jpg (in any folder) will be copied because it contains any number of characters followed by ".jpg". The files viola.jpg and cello.jPg will also be matched, but a file called jpg.txt will not be matched, nor will violin.jpg.backup be matched, nor "violinjpg".
  • *.mov – Like the first example, this pattern will match any sequence of characters which end with ".mov". The file picnic.mov and DogCow.MOV will be matched, but not a file called "dogcow.mov copy 2". (A pattern which would match the latter might look like *.mov* but this pattern would also match the file vcr.movers.txt)
  • index.txt – Since there are no asterisks or question marks in this pattern it will only match the file named "index.txt". It will also match "Index.TXT" and "iNdEx.TxT". Every index.txt file found in a subfolder of the Copy from folders will be copied.
  • ?p* – This pattern requires a file named with any single character followed by the letter P followed by at least one other character. Thus the file 2P200 would be matched, but not P200 or 22P200. Since the asterisk requires at least one character to match the file named 2P would not be matched by this pattern.

Note: These patterns are only applied to files. DateTree always enters folders to see if files inside need to be copied (but see the next section for folders that must be kept intact).

In the example shown above the rules were applied, and if any rule matched the file was copied. Sometimes you will want to copy most files, or files of many types. In this case it may be simpler to specify the patterns of files you wish to exclude from the copy. You can select all files, except those that match from the pop up menu labeled Copy:

If all files, except those that match is selected then files will not be copied if any of the patterns match, otherwise they will be copied.

Generally speaking it is not useful to copy hidden files, so DateTree does not copy them by default, nor does it enter hidden folders to look for files. You can allow hidden files and folders to be processed by selecting the checkbox provided. Note that DateTree always skips alias files and alias folders, hidden or not.

7. Copying entire folders
DateTree generally looks in folders to find files, creates (if necessary) subfolders of your Organize Into folder named for the appropriate dates, then copies the files directly into those subfolders. If files were originally contained within subfolder categories in the Copy From folders, those categories are lost as all files are copied directly into the dated folder. This can be a problem when this organization is important. So, instead of finding files inside some subfolders, you may want DateTree to copy these subfolders in their entirety.

An example of this will make it more clear: My camera has a feature for taking a sequence of images which can be combined into a panoramic photo on the computer. This sequence of images is stored in its own folder (let's say the folder is called Panorama01 and I took it on October 10, 2003). Normally DateTree would enter the folder Panorama01 and find all the photos inside. It would then copy each photo directly into the 2003-10-10 folder inside my Organize Into folder. By doing so, DateTree has discarded the information that all (and only) these images belong in one panorama. By teaching DateTree how to recognize my panorama folders it can copy the whole Panorama01 folder into the 2003-10-10 as a single unit. This will preserve my panorama organization.

Folder copying is configured similarly to the file copying rules discussed in the previous section. You use the same kind of patterns that have been previously described, except that – instead of file names – DateTree tries to match folder names against the patterns. Any folder which matches will be treated as if it were a file, and will be copied in its entirety (copied folders do not themselves have to match the file copying rules). In the example above I could have used a pattern like panorama* in the folder copying rules to cause the desired folder copying behaviors.

The last modification date of the folder itself will be used to determine which dated subfolder it is placed into within the Organize Into folder. Note that copied folders are copied in their entirety, any contained files are not subject to the file matching rules.

8. Advanced Patterns (Regular Expressions)
Most users of DateTree will be happy with the pattern matching rules described above. For those expert users who need to make more sophisticated patterns than can be specified with asterisks and question marks, DateTree allows regular expressions to be entered.

Regular expressions can be complex, and there isn't space in this document to explain them fully. Details on how to enter them into DateTree are provided here, but if you need a refresher on the syntax you may want to type "man perlre" into the terminal. If you're totally new to regular expressions and want to learn how to use them, you may want to consult a book or introductory website before attempting to use them in DateTree. (For a book, you could try Friedl's Mastering Regular Expressions – published by O'Reilly. I haven't read it, and so can't provide a review.)

The regular expressions should be entered in the Perl 5 style, enclosed by forward-slash (/) characters. Thus, the panorama example above could be entered as /panorama\d+/ to match only digits following the word panorama. All regular expressions are anchored. That is, the expression just presented is actually executed as /^panorama\d+$/ and matched against the file or folder name; do not enter the ^ and $ characters yourself, they are implied. The regular expressions are interpreted as being case-insensitive. Do not attempt to add modifiers after the closing forward-slash... that isn't supported here, and will result in your pattern being interpreted as a simple asterisk and question mark pattern.

9. Acknowledgments

Regular expression support is provided by the PCRE library package, which is open source software, written by Philip Hazel, and copyright by the University of Cambridge, England. It is available from ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/ or http://www.pcre.org/.

 Intro   Manual   See It   Get It 

Program and documentation are copyright. © 2003 by Colin Henein.
Accessed times. Last modified: .