lockfile: add holder info file for debugging stale locks

When a lock file is left behind (e.g., after a crash or SIGKILL), the
error message tells users to remove it manually but provides no
information about which process created it. This makes debugging
difficult, especially when multiple Git processes may be running.

Add an opt-in feature that creates a `.holder` file alongside each lock
file containing the PID of the process that created the lock. When
enabled via GIT_LOCK_HOLDER_INFO=1, this PID is displayed in lock
conflict error messages, making it easier to identify stale locks or
debug locking issues.

The holder file is:
- Created only when GIT_LOCK_HOLDER_INFO=1 is set (opt-in)
- Registered as a tempfile for automatic cleanup by signal handlers
- Stored separately from the lock file to maintain backward
  compatibility with existing tools that parse lock file contents

Example error message with the feature enabled:

  Unable to create '/path/to/.git/index.lock': File exists.

  Lock is held by process 12345.

  Another git process seems to be running in this repository...

Signed-off-by: Paulo Casaretto <[email protected]>

Author: pcasaretto

Documentation/git.adoc

@@ -1010,6 +1010,13 @@ be in the future).
 	the background which do not want to cause lock contention with
 	other operations on the repository.  Defaults to `1`.
 
+`GIT_LOCK_HOLDER_INFO`::
+	If this Boolean environment variable is set to `1`, Git will create
+	a `.holder` file alongside each lock file containing the PID of the
+	process that created the lock. This information is displayed in error
+	messages when a lock conflict occurs, making it easier to identify
+	stale locks or debug locking issues. Disabled by default.
+
 `GIT_REDIRECT_STDIN`::
 `GIT_REDIRECT_STDOUT`::
 `GIT_REDIRECT_STDERR`::

lockfile.c

@@ -6,6 +6,9 @@
 #include "abspath.h"
 #include "gettext.h"
 #include "lockfile.h"
+#include "parse.h"
+#include "strbuf.h"
+#include "wrapper.h"
 
 /*
  * path = absolute or relative path name
@@ -71,6 +74,59 @@ static void resolve_symlink(struct strbuf *path)
 	strbuf_reset(&link);
 }
 
+/*
+ * Lock holder info functions - write PID to a .holder file alongside
+ * the lock file for debugging stale locks. The holder file is registered
+ * as a tempfile so it gets cleaned up by signal/atexit handlers.
+ */
+
+static int lock_holder_info_enabled(void)
+{
+	return git_env_bool(GIT_LOCK_HOLDER_INFO_ENVIRONMENT, 0);
+}
+
+static struct tempfile *create_lock_holder_file(const char *lock_path, int mode)
+{
+	struct strbuf holder_path = STRBUF_INIT;
+	struct strbuf content = STRBUF_INIT;
+	struct tempfile *holder_tempfile = NULL;
+	int fd;
+
+	if (!lock_holder_info_enabled())
+		return NULL;
+
+	strbuf_addf(&holder_path, "%s%s", lock_path, LOCK_HOLDER_SUFFIX);
+	fd = open(holder_path.buf, O_WRONLY | O_CREAT | O_TRUNC, mode);
+	if (fd >= 0) {
+		strbuf_addf(&content, "%"PRIuMAX"\n", (uintmax_t)getpid());
+		if (write_in_full(fd, content.buf, content.len) < 0)
+			warning_errno(_("could not write holder file '%s'"),
+				      holder_path.buf);
+		close(fd);
+		holder_tempfile = register_tempfile(holder_path.buf);
+	}
+	strbuf_release(&content);
+	strbuf_release(&holder_path);
+	return holder_tempfile;
+}
+
+static int read_lock_holder_pid(const char *lock_path, uintmax_t *pid_out)
+{
+	struct strbuf holder_path = STRBUF_INIT;
+	struct strbuf content = STRBUF_INIT;
+	int ret = -1;
+
+	strbuf_addf(&holder_path, "%s%s", lock_path, LOCK_HOLDER_SUFFIX);
+	if (strbuf_read_file(&content, holder_path.buf, 32) > 0) {
+		*pid_out = strtoumax(content.buf, NULL, 10);
+		if (*pid_out > 0)
+			ret = 0;
+	}
+	strbuf_release(&holder_path);
+	strbuf_release(&content);
+	return ret;
+}
+
 /* Make sure errno contains a meaningful value on error */
 static int lock_file(struct lock_file *lk, const char *path, int flags,
 		     int mode)
@@ -80,9 +136,12 @@ static int lock_file(struct lock_file *lk, const char *path, int flags,
 	strbuf_addstr(&filename, path);
 	if (!(flags & LOCK_NO_DEREF))
 		resolve_symlink(&filename);
-
 	strbuf_addstr(&filename, LOCK_SUFFIX);
+
 	lk->tempfile = create_tempfile_mode(filename.buf, mode);
+	if (lk->tempfile)
+		lk->holder_tempfile = create_lock_holder_file(filename.buf, mode);
+
 	strbuf_release(&filename);
 	return lk->tempfile ? lk->tempfile->fd : -1;
 }
@@ -151,13 +210,26 @@ static int lock_file_timeout(struct lock_file *lk, const char *path,
 void unable_to_lock_message(const char *path, int err, struct strbuf *buf)
 {
 	if (err == EEXIST) {
-		strbuf_addf(buf, _("Unable to create '%s.lock': %s.\n\n"
-		    "Another git process seems to be running in this repository, e.g.\n"
+		struct strbuf lock_path = STRBUF_INIT;
+		uintmax_t holder_pid;
+
+		strbuf_addf(&lock_path, "%s%s", absolute_path(path), LOCK_SUFFIX);
+
+		strbuf_addf(buf, _("Unable to create '%s': %s.\n\n"),
+			    lock_path.buf, strerror(err));
+
+		if (lock_holder_info_enabled() &&
+		    !read_lock_holder_pid(lock_path.buf, &holder_pid))
+			strbuf_addf(buf, _("Lock is held by process %"PRIuMAX".\n\n"),
+				    holder_pid);
+
+		strbuf_addstr(buf, _("Another git process seems to be running in this repository, e.g.\n"
 		    "an editor opened by 'git commit'. Please make sure all processes\n"
 		    "are terminated then try again. If it still fails, a git process\n"
 		    "may have crashed in this repository earlier:\n"
-		    "remove the file manually to continue."),
-			    absolute_path(path), strerror(err));
+		    "remove the file manually to continue."));
+
+		strbuf_release(&lock_path);
 	} else
 		strbuf_addf(buf, _("Unable to create '%s.lock': %s"),
 			    absolute_path(path), strerror(err));
@@ -207,6 +279,8 @@ int commit_lock_file(struct lock_file *lk)
 {
 	char *result_path = get_locked_file_path(lk);
 
+	delete_tempfile(&lk->holder_tempfile);
+
 	if (commit_lock_file_to(lk, result_path)) {
 		int save_errno = errno;
 		free(result_path);
@@ -216,3 +290,9 @@ int commit_lock_file(struct lock_file *lk)
 	free(result_path);
 	return 0;
 }
+
+int rollback_lock_file(struct lock_file *lk)
+{
+	delete_tempfile(&lk->holder_tempfile);
+	return delete_tempfile(&lk->tempfile);
+}

lockfile.h

@@ -119,6 +119,7 @@
 
 struct lock_file {
 	struct tempfile *tempfile;
+	struct tempfile *holder_tempfile;
 };
 
 #define LOCK_INIT { 0 }
@@ -127,6 +128,12 @@ struct lock_file {
 #define LOCK_SUFFIX ".lock"
 #define LOCK_SUFFIX_LEN 5
 
+/* Suffix for holder info file that stores PID of lock holder: */
+#define LOCK_HOLDER_SUFFIX ".holder"
+#define LOCK_HOLDER_SUFFIX_LEN 7
+
+/* Environment variable to enable lock holder info (default: disabled) */
+#define GIT_LOCK_HOLDER_INFO_ENVIRONMENT "GIT_LOCK_HOLDER_INFO"
 
 /*
  * Flags
@@ -319,13 +326,10 @@ static inline int commit_lock_file_to(struct lock_file *lk, const char *path)
 
 /*
  * Roll back `lk`: close the file descriptor and/or file pointer and
- * remove the lockfile. It is a NOOP to call `rollback_lock_file()`
- * for a `lock_file` object that has already been committed or rolled
- * back. No error will be returned in this case.
+ * remove the lockfile and any associated holder file. It is a NOOP to
+ * call `rollback_lock_file()` for a `lock_file` object that has already
+ * been committed or rolled back. No error will be returned in this case.
  */
-static inline int rollback_lock_file(struct lock_file *lk)
-{
-	return delete_tempfile(&lk->tempfile);
-}
+int rollback_lock_file(struct lock_file *lk);
 
 #endif /* LOCKFILE_H */

t/meson.build

@@ -98,6 +98,7 @@ integration_tests = [
   't0028-working-tree-encoding.sh',
   't0029-core-unsetenvvars.sh',
   't0030-stripspace.sh',
+  't0031-lockfile-holder.sh',
   't0033-safe-directory.sh',
   't0034-root-safe-directory.sh',
   't0035-safe-bare-repository.sh',

t/t0031-lockfile-holder.sh

@@ -0,0 +1,72 @@
+#!/bin/sh
+
+test_description='lock file holder info tests
+
+Tests for PID holder info file alongside lock files.
+The feature is opt-in via GIT_LOCK_HOLDER_INFO=1.
+'
+
+. ./test-lib.sh
+
+test_expect_success 'holder info shown in lock error message when enabled' '
+	git init repo &&
+	(
+		cd repo &&
+		touch .git/index.lock &&
+		echo "99999" >.git/index.lock.holder &&
+		test_must_fail env GIT_LOCK_HOLDER_INFO=1 git add . 2>err &&
+		test_grep "Lock is held by process 99999" err
+	)
+'
+
+test_expect_success 'holder info not shown by default' '
+	git init repo2 &&
+	(
+		cd repo2 &&
+		touch .git/index.lock &&
+		echo "99999" >.git/index.lock.holder &&
+		test_must_fail git add . 2>err &&
+		# Should not crash, just show normal error without PID
+		test_grep "Unable to create" err &&
+		! test_grep "Lock is held by process" err
+	)
+'
+
+test_expect_success 'holder file created with correct PID during lock' '
+	git init repo3 &&
+	(
+		cd repo3 &&
+		echo content >file &&
+		# Create a lock and holder file manually to simulate a holding process
+		touch .git/index.lock &&
+		echo $$ >.git/index.lock.holder &&
+		# Verify our PID is shown in the error message
+		test_must_fail env GIT_LOCK_HOLDER_INFO=1 git add file 2>err &&
+		test_grep "Lock is held by process $$" err
+	)
+'
+
+test_expect_success 'holder info file cleaned up on successful operation when enabled' '
+	git init repo4 &&
+	(
+		cd repo4 &&
+		echo content >file &&
+		env GIT_LOCK_HOLDER_INFO=1 git add file &&
+		# After successful add, no lock or holder files should exist
+		! test -f .git/index.lock &&
+		! test -f .git/index.lock.holder
+	)
+'
+
+test_expect_success 'no holder file created by default' '
+	git init repo5 &&
+	(
+		cd repo5 &&
+		echo content >file &&
+		git add file &&
+		# Holder file should not be created when feature is disabled
+		! test -f .git/index.lock.holder
+	)
+'
+
+test_done