add readme and manpage

3 files changed, 123 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..bfb3429
--- /dev/null
+++ b/README.md
@@ -0,0 +1,96 @@
+# hm-reposync
+
+hm-reposync is a module for home-manager that allows tracking and managing
+out-of-(nix)store git repositories. The module generates and installs in the
+users `home.packages` a shell script called `reposync`. This command allows
+managing multiple repositories at once (clone, pull, stow, and more).
+Read `reposync.1` or run `man reposync` once installed for more info.
+
+# Examples
+
+In `flake.nix` (home-manager as NixOS module in this example):
+```nix
+{
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs/nixos-25.11";
+
+    home-manager = {
+      url = "github:nix-community/home-manager/release-25.11";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+    reposync = {
+      url = "git+https://git.tjkeller.xyz/hm-reposync";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+  };
+
+  outputs = { nixpkgs, ... }@inputs: let
+    system = {
+      # ...
+    };
+  in {
+    nixosConfigurations = {
+      example-host = nixpkgs.lib.nixosSystem {
+        inherit system;
+        # ...
+        modules = [
+          ./some-configuration.nix
+
+          inputs.home-manager.nixosModules.home-manager {
+            home-manager = {
+              # ...
+              useUserPackages = true;
+              sharedModules = [
+                inputs.reposync.hmModules.reposync
+                ./some-home-configuration.nix
+              ];
+            };
+          };
+        ];
+      };
+    };
+}
+```
+
+In home configuration:
+```nix
+reposync.enable = true;
+reposync.outOfStoreGitRepository = {
+  config = {
+    # Default git server is github (https)
+    repository = "github-user/dotconfig";
+    target = "src/config";  # Relative to home directory
+    extraCloneOptions = "--recurse-submodules";
+    stow = {
+      vim = {
+        targetPrefix = config.xdg.configHome;
+      };
+      misc = {
+        packages = "x11 zsh";
+      };
+    };
+  };
+  scripts = {
+    # Default repository will be scripts in this case
+    server = "https://git.tjkeller.xyz/";
+    targetPrefix = "/home/my-user/src";  # Final target will be /home/my-user/src/scripts
+    stow."*".target = ".local/bin";
+  };
+  hm-reposync = {
+    enable = lib.mkDefault false;
+    server = "https://git.tjkeller.xyz/";
+  };
+  awesome = {
+    server = "https://git.tjkeller.xyz/";
+    targetPrefix = config.xdg.configHome;
+  };
+};
+```
+
+Now the command `reposync -a` will sync all these repositories at once. It will
+clone them if they do not exist, and it will run pull to grab the latest
+changes IF there are no local changes. Individual repositories can be synced
+using `reposync <repo>`.
+
+Stow is a first class citizen, `stow --restow` will be ran on the packages
+tracked in `<repo>.stow.<package>` whenever synced.
diff --git a/hm-reposync.nix b/hm-reposync.nix
index b5706ea..83a1129 100644
--- a/hm-reposync.nix
+++ b/hm-reposync.nix
@@ -198,6 +198,7 @@ in {
       buildInputs = with pkgs; [git stow];
 
       installPhase = ''
+        # TODO install manpage
         mkdir -p $out/bin
         cp $src/bin/reposync $out/bin
         chmod +x $out/bin/reposync
diff --git a/reposync.1 b/reposync.1
new file mode 100644
index 0000000..a819466
--- /dev/null
+++ b/reposync.1
@@ -0,0 +1,26 @@
+.TH REPOSYNC 1 reposync
+.SH NAME
+reposync - sync git repositories tracked by home-manager
+.SH SYNOPSIS
+.B reposync
+[\fI\,OPTION\/\fR]... [\fI\,REPOSITORY\/\fR]...
+.SH DESCRIPTION
+reposync will clone, pull, stow, etc. the repositories it tracks through your
+home-manager config.
+.P
+use the following options to interact with the script:
+.TP
+\fB\-a\fR, \fB\-\-all\fR
+sync all repositories at once
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+run verbosely
+.TP
+\fB\-d\fR, \fB\-\-dry\-run\fR
+show what would happen without making changes
+.SH COPYRIGHT
+Copyright 2025 Tim Keller.
+MIT License.
+.P
+.P
+<https://TJKeller.xyz>