diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b064275
--- /dev/null
+++ b/README.md
@@ -0,0 +1,56 @@
+# git-heatmap
+
+simple but customizable heatmap for your local git repos written in Rust.
+
+![screenshot](screenshot.png)
+
+## Install
+
+### From source using cargo
+
+- clone the repository
+- `cd` into the repository
+- run `cargo install --path .`, cargo will build a release build and install it, for more info check the [cargo-install docs](https://doc.rust-lang.org/cargo/commands/cargo-install.html)
+
+## Usage
+
+```bash
+# can be ran in any directory that is a valid git repository
+$ git-heatmap
+
+# use any local repository from your system
+$ git-heatmap -r "/path/to/repo"
+
+# supports multiple repository
+$ git-heatmap -r "/path/to/repo" -r "/other/repo"
+
+# set what branch to check
+# if no -b flag is given all local branches of the repository will be checked
+$ git-heatmap -r "/path/to/repo" -b "main"
+
+# can also just pass the branches if you're already in a repository
+$ git-heatmap -b "main"
+
+# manually set which branches to check (separated by space)
+$ git-heatmap -r "/path/to/repo" -b "main other test"
+
+# supports checking different branches per repository however 
+# the number of -b flags needs to match the number of -p flags
+$ git-heatmap -r "/path/to/repo" -b "main" -r "/other/repo" -b "test"
+
+# an empty string can be passed for the -b flag so all branches get checked 
+# or to comply with the same number of branch lists per repo lists rule from above
+$ git-heatmap -r "/path/to/repo" -b "main" -r "other/repo" -b ""
+
+# filter by one or multiple authors 
+# without an -a flag all authors will be checked
+$ git-heatmap -a "username" -a "other"
+
+# choose from when to start the checking
+# if no --since flag is given it will start the search one year from the current date
+# if no --until date is given it will check for either 365 days since the start date or until the current day, depending on which one is closer
+$ git-heatmap --since "2013-08-23"
+
+# or choose a time span, both --since and --until must use a YYYY-MM-DD format
+$ git-heatmap --since "2013-08-23" --until "2024-08-23"
+```
diff --git a/screenshot.png b/screenshot.png
new file mode 100644
index 0000000..ace5705
Binary files /dev/null and b/screenshot.png differ