1 files changed, 53 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100755
index 0000000..e8ae7d1
--- /dev/null
+++ b/README.md
@@ -0,0 +1,53 @@
+# mds - Music Directory Transformer
+
+Transforms an Album directory into an Artist -> Album structure
+based on the metadata of the files in the directory.
+
+## Example
+
+```shell
+$ mds 'Jaco Pastorius - Jaco Pastorius (2010) [FLAC]'
+$ tree "Jaco Pastorius"/
+Jaco Pastorius/
+└── Jaco Pastorius (2010)
+    ├── 01 Donna Lee.flac
+    ├── ... more flac files
+    ├── dir.orig.name.txt
+    └── Jaco Pastorius - Jaco Pastorius (2010).cue
+$ mds "Jaco Pastorius - Invitation (1983) [FLAC]"
+$ mds "Jaco Pastorius - Word Of Mouth (1981) [FLAC]"
+$ tree "Jaco Pastorius"/
+Jaco Pastorius/
+└── Jaco Pastorius (2010)
+│   ├── 01 Donna Lee.flac
+│   ├── ... more flac files
+│   ├── dir.orig.name.txt
+│   └── Jaco Pastorius - Jaco Pastorius (2010).cue
+├── Invitation (1983)
+│    ├── ... more flac files
+│    ├── dir.orig.name.txt
+│    └── Jaco Pastorius - Invitation (1983).cue
+└── Word Of Mouth (1981)
+      ├── ... more flac files
+      ├── dir.orig.name.txt
+      └── Jaco Pastorius - Word of Mouth (1981).cue
+```
+
+Music Directory Transformer keeps a file `dir.orig.name.txt`
+inside the new transformed Album directory. This way Music Directory Transformer
+can transform back the directory to its original directory.
+
+```shell
+$ mds --revert "Jaco Pastorius/Jaco Pastorius (2010)"/
+$ tree "Jaco Pastorius"/
+Jaco Pastorius/
+└── Jaco Pastorius - Jaco Pastorius (2010) [FLAC]
+    ├── 01 Donna Lee.flac
+    ├── ... more flac files
+    ├── dir.orig.name.txt
+    └── Jaco Pastorius - Jaco Pastorius (2010).cue
+```
+
+## Caveats
+`mds` **does not rename or move the original directory** in both normal and reverse operation.
+`mds` will not touch the files in the original directory, it will only read its metadata.