hard-links: -H/--hard-links preserves inode relationships

Source files sharing (st_dev,st_ino) are recreated as hard links on the
destination; only the first member's data crosses the wire (siblings ride a
payload-less STATUS_HARDLINK frame). Ordering requires the single-FIFO-writer
receiver + forced sequential scan (documented). link()-failure falls back to a
byte-identical local copy. Rejects -s/--append. PROTOCOL_VERSION 2.11.0->2.12.0.
Review fixes: delete the dead HardLinkRegistry (ordering holds by FIFO writer),
and --existing no longer aborts when the first member is absent but the sibling
exists (leaves the sibling in place).

src/client/client_cli.c

@@ -475,6 +475,7 @@ static const OptionEntry OPTION_TABLE[] = {
     {"--copy-links", NULL, OPT_FLAG, offsetof(Config, copy_links)},
     {"--safe-links", NULL, OPT_FLAG, offsetof(Config, safe_links)},
     {"--copy-unsafe-links", NULL, OPT_FLAG, offsetof(Config, copy_unsafe_links)},
+    {"--hard-links", "-H", OPT_FLAG, offsetof(Config, preserve_hard_links)},
     {"--sparse", "-S", OPT_FLAG, offsetof(Config, preserve_sparse)},
     {"--inplace", NULL, OPT_FLAG, offsetof(Config, inplace)},
     {"--preallocate", NULL, OPT_FLAG, offsetof(Config, preallocate)},
@@ -552,6 +553,7 @@ static const NegatableOption NEGATABLE_OPTIONS[] = {
     {"copy-links", NULL, offsetof(Config, copy_links)},
     {"safe-links", NULL, offsetof(Config, safe_links)},
     {"copy-unsafe-links", NULL, offsetof(Config, copy_unsafe_links)},
+    {"hard-links", "H", offsetof(Config, preserve_hard_links)},
     {"sparse", "S", offsetof(Config, preserve_sparse)},
     {"inplace", NULL, offsetof(Config, inplace)},
     {"preallocate", NULL, offsetof(Config, preallocate)},

src/client/client_send.c

@@ -9,6 +9,7 @@
 #include "file.h"
 #include "file_list.h"
 #include "filter.h"
+#include "hardlink.h"
 #include "metadata.h"
 #include "log.h"
 #include "multiprocessing.h"
@@ -44,10 +45,13 @@ static const char* display_bytes(unsigned long long bytes, bool human_readable,
 
 /* Compiled scanner inputs that are shared read-only across scanner instances
  * and, in -m mode, across worker threads. `base_filters` owns the compiled
- * command-line + -C rules; the FileListSet allow-set lives in the Config. */
+ * command-line + -C rules; the FileListSet allow-set lives in the Config.
+ * `hardlinks` owns the --hard-links/-H link-group detection table (NULL when
+ * off) and is shared (mutex-guarded) across every scanner/worker of one scan. */
 typedef struct {
   ScannerOptions options;
   FilterRuleList* base_filters; /* owned; may be NULL */
+  HardLinkTable* hardlinks;     /* owned; may be NULL */
 } PreparedScanner;
 
 /* Build the scanner options for one scan. Returns false and logs on failure. */
@@ -55,6 +59,7 @@ static bool prepare_scanner(const Config* config, int num_threads, PreparedScann
   if (!out)
     return false;
   out->base_filters = NULL;
+  out->hardlinks = NULL;
   memset(&out->options, 0, sizeof(out->options));
 
   int rule_count = config->filters ? config->filters->size : 0;
@@ -107,6 +112,16 @@ static bool prepare_scanner(const Config* config, int num_threads, PreparedScann
   options->ignore_missing_args = config->ignore_missing_args || config->delete_missing_args;
   options->excluded_paths = NULL;
   options->excluded_mutex = NULL;
+  options->hardlinks = NULL;
+  if (config->preserve_hard_links) {
+    out->hardlinks = hardlink_table_create();
+    if (!out->hardlinks) {
+      filter_rule_list_free(out->base_filters);
+      out->base_filters = NULL;
+      return false;
+    }
+    options->hardlinks = out->hardlinks;
+  }
   return true;
 }
 
@@ -115,6 +130,8 @@ static void prepared_scanner_destroy(PreparedScanner* prepared) {
     return;
   filter_rule_list_free(prepared->base_filters);
   prepared->base_filters = NULL;
+  hardlink_table_destroy(prepared->hardlinks);
+  prepared->hardlinks = NULL;
 }
 
 /* True when some --files-from entry is an ancestor-or-equal directory of
@@ -1216,6 +1233,19 @@ static int send_chunk_with_removal(Client* client, Chunk* chunk, Config* config,
       change_emit_dir_sent(config, f);
       continue;
     }
+    /* --hard-links/-H sibling: a later member of a hard-link group that has no
+       data (its payload lives in the first member).  Transmit a dedicated
+       STATUS_HARDLINK frame carrying the first member's destination-relative
+       wire path so the receiver links this entry to that installed file. */
+    if (f->link_group != 0 && !f->link_first && f->hardlink_target != NULL) {
+      if (!send_status(client->file_descriptor, STATUS_HARDLINK) ||
+          !send_str(client->file_descriptor, file_wire_path(f)) ||
+          !send_int(client->file_descriptor, f->link_group) ||
+          !send_str(client->file_descriptor, f->hardlink_target))
+        return -1;
+      change_emit_file_sent(config, f);
+      continue;
+    }
     bool stream = f->data->data == NULL && f->data->size > 0;
     bool use_sendfile =
         (config->use_sendfile && !config->use_compression) || (stream && !config->use_compression);
@@ -1385,9 +1415,18 @@ static int scan_directory_multithreaded(void* pipeline_context) {
   if (!context->early_delete)
     prepared.options.excluded_paths = context->excluded_paths;
   bool dirs_mode = prepared.options.dirs;
+  /* -H also selects the sequential scanner (see the comment at the branch),
+   * so the loop below must choose the scanner by which object exists, not by
+   * --dirs alone. */
+  bool use_dscanner = dirs_mode || prepared.options.hardlinks;
   DirectoryScanner* dscanner = NULL;
   ParallelScanner* scanner = NULL;
-  if (dirs_mode) {
+  /* --hard-links/-H forces the sequential scanner even in -m mode: a hard-link
+     group's first member must be emitted before any of its siblings so the
+     receiver always links to an already-installed first member.  The parallel
+     scanner hands different subdirectories to different worker threads, which
+     can reorder a group whose members span directories. */
+  if (use_dscanner) {
     dscanner =
         directory_scanner_create_with_options(context->config->send_directory, &prepared.options);
   } else {
@@ -1404,12 +1443,12 @@ static int scan_directory_multithreaded(void* pipeline_context) {
   bool failed = false;
   Chunk* current_chunk;
   while (1) {
-    if (dirs_mode)
+    if (use_dscanner)
       current_chunk = directory_scanner_next(dscanner);
     else
       current_chunk = parallel_scanner_next(scanner);
     if (current_chunk == NULL) {
-      failed = dirs_mode ? directory_scanner_failed(dscanner) : parallel_scanner_failed(scanner);
+      failed = use_dscanner ? directory_scanner_failed(dscanner) : parallel_scanner_failed(scanner);
       break;
     }
     if (context->config->use_delete && !context->early_delete) {
@@ -1434,9 +1473,9 @@ static int scan_directory_multithreaded(void* pipeline_context) {
   /* Capture the scanner results BEFORE destroying the scanner objects (the
      io_error flag lives on the scanner, so reading it after destroy would be a
      use-after-free). */
-  bool had_io =
-      dirs_mode ? directory_scanner_had_io_error(dscanner) : parallel_scanner_had_io_error(scanner);
-  if (dirs_mode)
+  bool had_io = use_dscanner ? directory_scanner_had_io_error(dscanner)
+                             : parallel_scanner_had_io_error(scanner);
+  if (use_dscanner)
     directory_scanner_destroy(dscanner);
   else
     parallel_scanner_destroy(scanner);

src/client/client_validation.c

@@ -69,6 +69,21 @@ bool validate_config(const Config* config) {
                 "full transfer)");
     return false;
   }
+  /* --hard-links/-H transmits each later group member as a dedicated per-file
+     STATUS_HARDLINK frame, which chunk serialization -s does not support; and a
+     hard-links sibling carries no payload, so the tail-resume of --append is
+     meaningless for it.  Both combinations are rejected up front rather than
+     silently degrading. */
+  if (config->preserve_hard_links && config->use_chunk_serialization) {
+    log_message(LOG_LEVEL_ERROR,
+                "--hard-links/-H cannot be combined with -s (chunk serialization)");
+    return false;
+  }
+  if (config->preserve_hard_links && (config->append || config->append_verify)) {
+    log_message(LOG_LEVEL_ERROR,
+                "--hard-links/-H cannot be combined with --append/--append-verify");
+    return false;
+  }
   if (config->log_file_format && !config->log_file) {
     log_message(LOG_LEVEL_ERROR, "--log-file-format requires --log-file");
     return false;

src/client/scanner.c

@@ -165,6 +165,34 @@ static bool entry_passes_selection(const FileListSet* file_list, const FilterRul
   return true;
 }
 
+/* Apply --hard-links (-H) detection to one regular File.  On a sibling (a
+ * later member of an already-seen source inode) the File keeps the group id
+ * and the first member's wire path but carries NO data payload (size 0); the
+ * first member is left untouched (data present, link_first).  Allocation
+ * failure is fatal: the scanner is marked failed. */
+static void scanner_assign_hardlink(DirectoryScanner* scanner, HardLinkTable* table, File* file,
+                                    const struct stat* stats) {
+  if (!table || !file || !stats)
+    return;
+  int gid;
+  bool is_first;
+  char* first_path = NULL;
+  if (!hardlink_table_assign(table, file_wire_path(file), stats->st_dev, stats->st_ino, &gid,
+                             &is_first, &first_path)) {
+    if (scanner)
+      scanner->failed = true;
+    return;
+  }
+  file->link_group = gid;
+  file->link_first = is_first;
+  if (!is_first) {
+    file->hardlink_target = first_path;
+    file->data->size = 0;
+  } else {
+    free(first_path);
+  }
+}
+
 /* Append `rel` to the caller's exclusion sink, taking `mtx` when shared across
    parallel worker threads.  Returns false on allocation failure (list left
    unchanged). */
@@ -356,6 +384,7 @@ DirectoryScanner* directory_scanner_create_with_options(const char* root_directo
   scanner->io_error = false;
   scanner->dirs_mode = options->dirs;
   scanner->relative_mode = options->relative && options->file_list != NULL;
+  scanner->hardlinks = options->hardlinks;
   scanner->prune_empty_dirs = options->prune_empty_dirs;
   scanner->dirs_root_emitted = false;
   scanner->list_index = 0;
@@ -892,6 +921,8 @@ Chunk* directory_scanner_next(DirectoryScanner* scanner) {
         file->send_path = rel_copy;
         rel_copy = NULL;
       }
+      if (scanner->hardlinks && S_ISREG(stats.st_mode))
+        scanner_assign_hardlink(scanner, scanner->hardlinks, file, &stats);
       if (scanner->use_metadata)
         file->metadata = file_metadata_create(&stats);
       if (scanner->use_metadata && !file->metadata) {
@@ -1207,6 +1238,24 @@ static void scan_root_entry(const ScannerOptions* options, const FilterNode* roo
     file->send_path = rel;
     rel = NULL;
   }
+  if (options->hardlinks && S_ISREG(st.st_mode)) {
+    int gid;
+    bool is_first;
+    char* first_path = NULL;
+    if (!hardlink_table_assign((HardLinkTable*)options->hardlinks, file_wire_path(file), st.st_dev,
+                               st.st_ino, &gid, &is_first, &first_path)) {
+      ps->failed = true;
+    } else {
+      file->link_group = gid;
+      file->link_first = is_first;
+      if (!is_first) {
+        file->hardlink_target = first_path;
+        file->data->size = 0;
+      } else {
+        free(first_path);
+      }
+    }
+  }
   if (options->use_metadata)
     file->metadata = file_metadata_create(&st);
   if (options->use_metadata && !file->metadata) {

src/client/scanner.h

@@ -4,6 +4,7 @@
 #include "chunk.h"
 #include "file_list.h"
 #include "filter.h"
+#include "hardlink.h"
 #include "protocol.h"
 #include "queue.h"
 #include <dirent.h>
@@ -64,6 +65,11 @@ typedef struct {
    * instead of failing (the --dirs generator is the only scanner path that
    * observes a listed-but-missing entry). */
   bool ignore_missing_args;
+  /* --hard-links (-H): shared, mutable (mutex-guarded) link-group detection
+   * table, NULL when -H is off.  Owned by the caller (client_send), shared
+   * read-only here; the parallel scanner passes it unchanged to every worker so
+   * one table detects every group across all subdirectories. */
+  HardLinkTable* hardlinks;
 } ScannerOptions;
 
 /* Internal per-scanner filter state. FilterNode chains represent the ordered
@@ -124,6 +130,9 @@ typedef struct {
      --ignore-errors the scan continues past it and the caller decides what to
      do; `failed` is reserved for fatal errors that always abort the scan. */
   bool io_error;
+  /* --hard-links (-H): shared link-group detection table (see ScannerOptions).
+     NULL when -H is off. */
+  HardLinkTable* hardlinks;
 } DirectoryScanner;
 
 typedef struct {

src/client/usage.c

@@ -180,6 +180,7 @@ void print_usage(void) {
   printf("  --copy-links        Transform symlinks into referent files\n");
   printf("  --safe-links        Skip symlinks that point outside transfer tree\n");
   printf("  --copy-unsafe-links  Only transform unsafe symlinks into referent files\n");
+  printf("  -H, --hard-links    Preserve hard-link relationships across the transfer\n");
   printf("  -S, --sparse        Handle sparse files efficiently\n");
   printf("  --inplace           Update files in-place (no temp+rename)\n");
   printf(