Brendan Dawes
The Art of Form and Code

A Handy Command Line Script to Generate a Readme File for Project Delivery

When a project is completed I often have many files to deliver to the client. When I'm delivering these files I like to create folders for the different formats such as mp4, png, psd, tif etc. Alongside that I think it's good practice to include a simple readme.txt file which details the location of these files together with a simple explanation of what they are and if necessary how they're to be used.

To generate this list of files I could type them into a text file one by one, which would be really laborious. Instead I turned to the terminal to generate this list. Navigating to the parent folder of my deliverables and typing ls in the terminal will give me a basic list like this:

mp4     psb     psd     readme.txt  tif

As you can see though it just gives me the folder and not the contents of those folders. We can change that by typing instead ls -R which is the recursive flag to print the folder contents like this:

mp4     psb     psd     readme.txt  tif

./mp4:
client-project-video-1080.mp4   client-project-video-igtv.mp4
client-project-video-2160.mp4

./psb:
client-project-government_28000x16200.psb

./psd:
client-project-print_renders_4800x2700.psd

./tif:
client-project-banking_4800x2700.tif
client-project-government_28000x16200.tif
client-project-government_4800x2700.tif
client-project-media_4800x2700.tif
client-project-retail_4800x2700.tif
client-project-technology_4800x2700.tif

This is certainly better and usable, but I wanted to go a stage further and have some more info such as file size and date.

To do this I amended a few more flags which gives me that information and makes things a bit more readable:

ls -lrtshg -R

Which then gives me:

./psb:
total 4358496
4358496 -rw-r--r--@ 1 staff   2.1G 17 Feb 13:20 client-project-government_28000x16200.psb

./tif:
total 1016168
33128 -rw-r--r--@ 1 staff    16M 14 Feb 10:29 client-project-technology_4800x2700.tif
35184 -rw-r--r--@ 1 staff    17M 14 Feb 10:29 client-project-retail_4800x2700.tif
33128 -rw-r--r--@ 1 staff    16M 14 Feb 10:29 client-project-media_4800x2700.tif
31080 -rw-r--r--@ 1 staff    15M 14 Feb 10:30 client-project-government_4800x2700.tif
31072 -rw-r--r--@ 1 staff    15M 14 Feb 10:30 client-project-banking_4800x2700.tif
852576 -rw-r--r--@ 1 staff   401M 17 Feb 13:21 client-project-government_28000x16200.tif

./mp4:
total 1278336
688256 -rw-r--r--@ 1 staff   333M 18 Feb 12:14 client-project-video-2160.mp4
295040 -rw-r--r--@ 1 staff   132M 18 Feb 12:18 client-project-video-1080.mp4
295040 -rw-r--r--@ 1 staff   135M 19 Feb 11:46 client-project-video-igtv.mp4

That's now too much info — I don't want all that permissions stuff or the inode number. Luckily we can use awk to format the output. After some trial and error I created this little script that will create a nice list:

ls -lrtshg -R | awk '{ if($1 ~ /\//) print $1; print $5,$6, $7, $8,$9}'

This then gives me this nicely formatted list with just the right amount of information:

./psd:

114M 14 Feb 10:30 client-project-print_renders_4800x2700.psd

./psb:

2.1G 17 Feb 13:20 client-project-government_28000x16200.psb

./tif:

16M 14 Feb 10:29 client-project-technology_4800x2700.tif
17M 14 Feb 10:29 client-project-retail_4800x2700.tif
16M 14 Feb 10:29 client-project-media_4800x2700.tif
15M 14 Feb 10:30 client-project-government_4800x2700.tif
15M 14 Feb 10:30 client-project-banking_4800x2700.tif
401M 17 Feb 13:21 client-project-government_28000x16200.tif

./mp4:

333M 18 Feb 12:14 client-project-video-2160.mp4
132M 18 Feb 12:18 client-project-video-1080.mp4
135M 19 Feb 11:46 client-project-video-igtv.mp4

Even better I can write all that info to a file by simply appending > listing.txt to the command. Now I have a text file containing a listing of all the files, ready for me to edit with further descriptions.

Of course that command is a little bit long to remember each time, so I would suggest you create a bash function as an alias. I have mine so I can just type list and it does its thing.

I should mention the excellent tree library for the command line which can create a tree like structure of a directory listing as well as export that list to HTML. Also if you want to auto generate and add image sizes to your filenames I highly recommend A Better Finder Rename.