From 9865dba535620831ae7cab395bf404f8f464df0e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tom=C3=A1s=20Rivera?= <tomas.riveral@icloud.com>
Date: Sat, 13 Jun 2026 19:54:03 +0200
Subject: [PATCH] docs: write README.md

---
 README.md | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 67 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 4c28b81..3068663 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,68 @@
 # Nix-Git-Cherry-Picker
-Git helper to cherry pick commits between two machine with the same nix config repository, but on two different branches
+
+This small shell script helps cherry-picking commits between two git branches (supposedly used as a nix configuration on two machines).
+
+It does not handle merge conflicts automatically. It will instruct you to do it yourself.
+#### Installation
+
+##### Nix
+
+In your flake.nix :
+```nix
+nix-git-cherry-picker = {
+    url = "github:tomasriveral/nix-git-cherry-picker";
+};
+```
+Or, if you want to follow the inputs :
+```nix
+nix-git-cherry-picker = {
+  url = "github:tomasriveral/nix-git-cherry-picker";
+  inputs.flake-utils.follows = "flake-utils";
+  inputs.nixpkgs.follows = "nixpkgs";
+};
+```
+You can refer to the package as `inputs.nix-git-cherry-picker.packages.${pkgs.system}.default`
+##### Manual
+
+```sh
+git clone https://github.com/tomasriveral/Nix-Git-Cherry-Picker
+cd Nix-Git-Cherry-Picker
+./ngcp.sh
+```
+#### Usage
+
+For best practices (and to avoid merge conflicts), you should push to your remote before shutting down your machine or running ngcp from another machine.
+
+```
+Usage: ngcp [mode] [options]
+Mode:
+ pick <commit 1> <commit2> <...>    Cherry-pick commits for the remote branch.
+ pull                               Pulls the changes to the local branch.
+Options:
+  --automatic                       Exit with no changes if merge conflict and instructs the user to pull manually. Use this option for automation.
+```
+#### Configuration
+
+The programs will create a default configuration if the `~/.config/nix-git-cherry-picker/config.json` doesn't exist.
+
+```json
+{
+  "localBranch": "laptop",
+  "remoteBranch": "desktop",
+  "nixConfigPath": "/home/tomasr/nixos/"
+}
+```
+
+`localBranch` is the git branch on your current machine.
+
+`remoteBranch` is the git branch on your other machine.
+
+`nixConfigPath` is the path to your cloned git repository.
+
+#### Note
+This project was primarily designed to handle [my nixos configuration](github.com/tomasriveral/nixos) and, as such, meets my needs. This means that :
+
+* Even though this project could actually work for any other git project (nixos configuration or not, hosted on github or not), I do not guarantee it will stay like that. I might add a nix-specific feature in the future.
+* It only works on two branches. (You could reuse the same branch on multiple machines).
+
+If you want to use this project for other purposes, you are free to open a PR or ask kindly, I might implement (or not) modifications.