Add readme

1 files changed, 58 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..07785e8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,58 @@
+# slack2gitlab-emoji-sync
+
+> syncs emojis from Slack to GitLab ❗
+
+No Slack Enterprise Grid or API access required. The script uses Slack's
+desktop app logs to extract custom emojis and sync them to GitLab.
+
+## Requirements
+
+- Perl or Docker
+- Slack _native_ 🚎 ie the desktop app
+
+## Usage
+
+### Locally
+
+1. Open Slack, click the emoji picker, switch to the custom page, and slowly
+   scroll until you reach the end of the list.
+
+1. Then run the sync script:
+
+    ```sh
+    export SLACK_WORKSPACE="..."    # https://slack.com/help/articles/221769328-Locate-your-Slack-URL-or-ID
+    export GITLAB_TOKEN="..."       # https://gitlab.com/-/user_settings/personal_access_tokens
+    export GITLAB_GROUP_PATH="..."  # eg my_group
+    export GITLAB_URL="..."         # optional, defaults to https://gitlab.com
+    export SLACK_LOGS_DIR="..."     # optional, defaults to $HOME/Library/Application Support/Slack/logs/default
+    ./sync <filter>                 # where filter is a regex to match emoji names in Slack, eg '.*' for all emojis
+    ```
+
+### Docker
+
+1. Build the Docker image:
+
+    ```sh
+    docker build -t slack2gitlab-emoji-sync .
+    ```
+
+1. Open Slack, click the emoji picker, and slowly scroll until you reach the
+   end of the list.
+
+1. Run the sync script:
+    ```sh
+    docker run --rm -it \
+        -e SLACK_WORKSPACE="..." \
+        -e GITLAB_TOKEN="..." \
+        -e GITLAB_GROUP_PATH="..." \
+        -e SLACK_LOGS_DIR="/slack-logs" \
+        -v "$HOME/Library/Application Support/Slack/logs/default":/slack-logs \
+        slack2gitlab-emoji-sync <filter>  # where filter is a regex to match emoji names in Slack, eg '.*' for all emojis
+    ```
+
+    _Note: Adjust the Slack logs directory depending on your OS._
+
+## Caveats
+
+- If the same custom emoji is under different names in Slack, only the first
+  one is synced.