1 files changed, 52 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..03b5f29
--- /dev/null
+++ b/README.md
@@ -0,0 +1,52 @@
+# ls-imitation
+
+C project that reimplements the functionality of the Unix `ls -l` command.  The
+program parses command-line arguments, retrieves file information, and formats
+the output similar to GNU `ls`.
+
+<img src="ls.png" />
+
+## Features
+
+- Implements `ls -l` style output:
+    - File type and permissions
+    - Number of links
+    - Owner and group
+    - File size
+    - Modification time
+    - Filename
+- Handles both files and directories from command-line arguments
+- Prints directory headers and separators when multiple directories are listed
+- Detects whether output is a terminal (`isatty`) and adjusts formatting
+- Maintains a linked-list of file entries with conversion to arrays
+- Supports sorting file entries by filename
+- Column alignment for neat tabular output
+- Edge cases handled (empty input, single file, multiple directories, etc.)
+- Simple build system via `Makefile`
+
+## Building
+
+### On Linux
+
+```bash
+git clone https://git.scratko.xyz/ls-imitation
+cd ls-imitation
+make
+./ls-imitation
+```
+
+## Usage
+
+The program mimics the behavior of `ls -l`.  Instead of calling `ls -l`, run:
+
+```bash
+./ls-imitation <files or directories>
+```
+### Examples
+
+```bash
+./ls-imitation
+./ls-imitation file.txt
+./ls-imitation dir1 dir2
+./ls-imitation file1.txt dir/
+```