9d • Unix / Linux CLI
My Perfected File Naming Format
Today I wanted to share my perfected file naming format and explain why it looks the way it does on all the files you've seen so far and will see in the future.
First, l'll introduce it to you, then I'll break it down. I've also included a .pdf for easy reading and a .txt file for using as a reference in your terminal.
======
THE NAMING FORMAT:
title_descriptor_YYYYMMDDtHHMM_m####.ext
title_descriptor_YYYYMMDDtHHMM_p####.ext
For this post it would be:
theforge_my_perfected_file_naming_format_20260405t0714_m0500.txt
======
THE COMPONENTS:
- title_descriptor — To represent the contents, the name should be all lowercase words, separated by underscores; no capital letters, spaces, dashes, or special characters.
- YYYYMMDD — To represent the date, I use an ISO 8601 adjacent format with a 4 digit year, a 2 digit month, and a 2 digit day (the date of creation or export).
- tHHMM — To represent the time, I also use an ISO 8601 adjacent format with a lowercase letter ‘t’ to indicate the start of the documented time, followed by 24-hour time, then the hour and minutes.
For the UTC time offset, I use two different indicators depending on if the timezone is ahead, or behind, UTC.
- m#### — To represent a time behind UTC the offset indicating character is an "m" for minus # of hours (e.g., m0500 = UTC-5).
- p#### — To represent UTC or a time ahead of UTC, the offset indicating character is a "p" for plus # of hours, and standard UTC is simply “0000” (e.g., p0200 = UTC+2 and p0000 = UTC).
- .ext — To represent the file type I use the corresponding file extension (e.g., .txt, .md, .pdf, .csv, etc.) at the end. If I don't know the file type, or the file’s contents will be switching file types, I just use ".ext" as a placeholder.
EXAMPLES:
ai_assistant_summary_20251005t1140_m0500.txt
guardian_druid_builds_20251102t1745_p0200.pdf
unix_cli_reference_20251001t0930_p0000.txt
======
THE MANDATORY RULES:
1. Use only lowercase letters, numbers, periods and underscores.
2. No hyphens, (-), capital letters, spaces, or special characters (e.g.,+, %, $, etc.).
3. The timestamp must always include tHHMM to represent time.
4. The UTC offset must always use m#### or p#### to reflect the time zone and UTC offset accurately.
======
THE WHY
This file naming format has many benefits over a standard "letters and spaces" filename. And here’s why.
First, I only use lowercase letters, numbers, periods, and underscores, specifically. No hyphens, spaces, or special characters. This is aligned with the POSIX.1-2017 standard or the “Portable Filename Character Set”. But I specifically avoid the hyphens they include. This is because hyphens give you the problem of text in a file in the terminal being misread as a command with corresponding command flags. Because nearly all command flags use a hyphen as their initiating character, I only use underscores, periods, numbers, and lowercase letters, to prevent the system from misinterpreting them.
Second, for the date and time marker I use a modified ISO 8601 date and time standard. The ISO 8601 standard fails in a few key ways. First, the standard uses hyphens in their timestamps which I have outlined as an issue. Secondly, by breaking up their timestamp ISO made it more difficult for computers to parse and interpret correctly; by keeping them together, with a “t” separating them, I’ve made it easy for a user to grep (search) for the date and timestamp using my format without any weird interactions. Third, the ISO 8601 standard uses seconds in their timestamps, but I do not. Including seconds is an issue because no human clock will give you seconds. This means I’d have to lie and make stuff up. On top of that if I need to handle multiple versions within the same minute I can easily do that in the title descriptor via version, and should anyway. Finally, most naming schemes ignore time zones entirely which leads to confusion when files are shared across different regions. By using “m####” or “p####” to indicate the UTC offset I am able to record the specific timezone and time used accurately. This makes it globally understandable in ways that others aren’t. The timestamp in the file name and document stays the original date and timestamp of creation or the finalization for publishing. This helps keep ideas safely preserved in time via the timestamp while metadata can be used for anything else. This is why my timestamps are in the format, “YYYYMMDDtHHMM_p####”; because my way humans can read it, machines can parse it, and AI can understand it. This makes it optimal for all potential users of the information.
Third, the “topic_descriptor” portion of the timestamp is key but where you need to be specifically careful and consistent. For my documents for The Forge I use “theforge_document_title” so that way I can search for all of The Forge’s documents with the first part, or the specific document title with the second. And I use the title of the work explicitly, with other descriptors like version “v#” (e.g. v2) at the end, to ensure there is no semantic misinterpretation from a just group of associated keywords.
Fourth, “Why is the descriptor at the front and the timestamp at the end?” you may ask, well let me explain. By putting the topic name at the beginning of the filename I force the computer to sort the documents alphabetically. This makes it even easier for me to find what I am looking for. And since I put the name of the container for the document, like “theforge”, at the front of the title, all of The Forge’s documents will be grouped together and sorted alphabetically within that group. If I were to put the timestamp at the beginning then the same timestamps from every other day would all be next to them, increasing confusion on top of being useless. In addition, sorting by date and time is already available in every major GUI, making it redundant.
Fifth, On all of my documents, independent of type, you will see the file name as the first line. I do this to ensure filename preservation across document type conversion and for an eternalized proper identification within the document itself. This is also useful for recovering the name of a document if the title gets mangled or deleted somehow. All of which make it worthwhile to include the filename as the first line.
In conclusion, the file naming format that I have outlined is as close to “perfect” for the job as I could hope. It addresses numerous common pitfalls of typical file naming schemes. And this way filenames are human readable and still machine parsable. Save yourself the headaches and try it now.
- Michael Roby II
END
======
2
2 comments
My Perfected File Naming Format
