lockfile: add PID file for debugging stale locks

When a lock file is held, it can be helpful to know which process owns
it, especially when debugging stale locks left behind by crashed
processes. Add an optional feature that creates a companion PID file
alongside each lock file, containing the PID of the lock holder.

For a lock file "foo.lock", the PID file is named "foo-pid.lock".

The PID file is created when a lock is acquired (if enabled), and
automatically cleaned up when the lock is released (via commit or
rollback). The file is registered as a tempfile so it gets cleaned up
by signal and atexit handlers if the process terminates abnormally.

When a lock conflict occurs, the code checks for an existing PID file
and, if found, uses kill(pid, 0) to determine if the process is still
running. This allows providing context-aware error messages:

  Lock is held by process 12345. Wait for it to finish, or remove
  the lock file to continue.

Or for a stale lock:

  Lock was held by process 12345, which is no longer running.
  Remove the stale lock file to continue.

The feature is controlled via core.lockfilePid configuration, which
accepts per-component values similar to core.fsync:

  - none: Disable for all components (default)
  - all: Enable for all components
  - index, config, refs, commit-graph, midx, shallow, gc, other:
    Enable for specific components

Multiple components can be combined with commas:

  git config core.lockfilePid index,config

Each lock file call site specifies which component it belongs to,
allowing users fine-grained control over which locks create PID files.

Existing PID files are always read when displaying lock errors,
regardless of the core.lockfilePid setting. This ensures helpful
diagnostics even when the feature was previously enabled and later
disabled.

Signed-off-by: Paulo Casaretto <pcasaretto@gmail.com>

Author: pcasaretto

Documentation/config/core.adoc

@@ -348,6 +348,31 @@ confusion unless you know what you are doing (e.g. you are creating a
 read-only snapshot of the same index to a location different from the
 repository's usual working tree).
 
+core.lockfilePid::
+	A comma-separated list of components for which Git should create
+	a PID file alongside the lock file. When a lock acquisition fails
+	and a PID file exists, Git can provide additional diagnostic
+	information about the process holding the lock, including whether
+	it is still running.
++
+This feature is disabled by default. You can enable it for specific
+components or use `all` to enable for all components.
++
+* `none` disables PID file creation for all components.
+* `index` creates PID files for index lock operations.
+* `config` creates PID files for config file lock operations.
+* `refs` creates PID files for reference lock operations.
+* `commit-graph` creates PID files for commit-graph lock operations.
+* `midx` creates PID files for multi-pack-index lock operations.
+* `shallow` creates PID files for shallow file lock operations.
+* `gc` creates PID files for garbage collection lock operations.
+* `other` creates PID files for other miscellaneous lock operations.
+* `all` enables PID file creation for all components.
++
+The PID file is named by inserting `-pid` before the `.lock` suffix.
+For example, if the lock file is `index.lock`, the PID file will be
+`index-pid.lock`.
+
 core.logAllRefUpdates::
 	Enable the reflog. Updates to a ref <ref> is logged to the file
 	"`$GIT_DIR/logs/<ref>`", by appending the new and old

Documentation/git.adoc

@@ -1010,6 +1010,16 @@ 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_PID_INFO`::
+	If this Boolean environment variable is set to `1`, Git will create
+	a `.lock.pid` 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. The PID files are automatically
+	cleaned up via signal and atexit handlers; however, if a process is
+	terminated abnormally (e.g., SIGKILL), the file may remain as a stale
+	indicator. Disabled by default.
+
 `GIT_REDIRECT_STDIN`::
 `GIT_REDIRECT_STDOUT`::
 `GIT_REDIRECT_STDERR`::

apply.c

@@ -4173,7 +4173,8 @@ static int build_fake_ancestor(struct apply_state *state, struct patch *list)
 		}
 	}
 
-	hold_lock_file_for_update(&lock, state->fake_ancestor, LOCK_DIE_ON_ERROR);
+	hold_lock_file_for_update(&lock, state->fake_ancestor, LOCK_DIE_ON_ERROR,
+				  LOCKFILE_PID_OTHER);
 	res = write_locked_index(&result, &lock, COMMIT_LOCK);
 	discard_index(&result);
 
@@ -4830,7 +4831,8 @@ static int apply_patch(struct apply_state *state,
 		if (state->index_file)
 			hold_lock_file_for_update(&state->lock_file,
 						  state->index_file,
-						  LOCK_DIE_ON_ERROR);
+						  LOCK_DIE_ON_ERROR,
+						  LOCKFILE_PID_INDEX);
 		else
 			repo_hold_locked_index(state->repo, &state->lock_file,
 					       LOCK_DIE_ON_ERROR);

builtin/commit.c

@@ -540,7 +540,7 @@ static const char *prepare_index(const char **argv, const char *prefix,
 	path = repo_git_path(the_repository, "next-index-%"PRIuMAX,
 			     (uintmax_t) getpid());
 	hold_lock_file_for_update(&false_lock, path,
-				  LOCK_DIE_ON_ERROR);
+				  LOCK_DIE_ON_ERROR, LOCKFILE_PID_OTHER);
 
 	create_base_index(current_head);
 	add_remove_files(&partial);

builtin/credential-store.c

@@ -67,7 +67,8 @@ static void rewrite_credential_file(const char *fn, struct credential *c,
 	int timeout_ms = 1000;
 
 	repo_config_get_int(the_repository, "credentialstore.locktimeoutms", &timeout_ms);
-	if (hold_lock_file_for_update_timeout(&credential_lock, fn, 0, timeout_ms) < 0)
+	if (hold_lock_file_for_update_timeout(&credential_lock, fn, 0, timeout_ms,
+					      LOCKFILE_PID_CONFIG) < 0)
 		die_errno(_("unable to get credential storage lock in %d ms"), timeout_ms);
 	if (extra)
 		print_line(extra);

builtin/difftool.c

@@ -636,7 +636,8 @@ static int run_dir_diff(struct repository *repo,
 			struct lock_file lock = LOCK_INIT;
 			strbuf_reset(&buf);
 			strbuf_addf(&buf, "%s/wtindex", tmpdir.buf);
-			if (hold_lock_file_for_update(&lock, buf.buf, 0) < 0 ||
+			if (hold_lock_file_for_update(&lock, buf.buf, 0,
+					      LOCKFILE_PID_OTHER) < 0 ||
 			    write_locked_index(&wtindex, &lock, COMMIT_LOCK)) {
 				ret = error("could not write %s", buf.buf);
 				goto finish;

builtin/fast-import.c

@@ -1734,7 +1734,8 @@ static void dump_marks(void)
 		return;
 	}
 
-	if (hold_lock_file_for_update(&mark_lock, export_marks_file, 0) < 0) {
+	if (hold_lock_file_for_update(&mark_lock, export_marks_file, 0,
+				      LOCKFILE_PID_OTHER) < 0) {
 		failure |= error_errno(_("unable to write marks file %s"),
 				       export_marks_file);
 		return;

builtin/gc.c

@@ -749,7 +749,7 @@ static const char *lock_repo_for_gc(int force, pid_t* ret_pid)
 
 	pidfile_path = repo_git_path(the_repository, "gc.pid");
 	fd = hold_lock_file_for_update(&lock, pidfile_path,
-				       LOCK_DIE_ON_ERROR);
+				       LOCK_DIE_ON_ERROR, LOCKFILE_PID_GC);
 	if (!force) {
 		static char locking_host[HOST_NAME_MAX + 1];
 		static char *scan_fmt;
@@ -1017,7 +1017,7 @@ int cmd_gc(int argc,
 	if (daemonized) {
 		char *path = repo_git_path(the_repository, "gc.log");
 		hold_lock_file_for_update(&log_lock, path,
-					  LOCK_DIE_ON_ERROR);
+					  LOCK_DIE_ON_ERROR, LOCKFILE_PID_GC);
 		dup2(get_lock_file_fd(&log_lock), 2);
 		atexit(process_log_file_at_exit);
 		free(path);
@@ -1797,7 +1797,8 @@ static int maintenance_run_tasks(struct maintenance_run_opts *opts,
 	struct repository *r = the_repository;
 	char *lock_path = xstrfmt("%s/maintenance", r->objects->sources->path);
 
-	if (hold_lock_file_for_update(&lk, lock_path, LOCK_NO_DEREF) < 0) {
+	if (hold_lock_file_for_update(&lk, lock_path, LOCK_NO_DEREF,
+				      LOCKFILE_PID_GC) < 0) {
 		/*
 		 * Another maintenance command is running.
 		 *
@@ -2561,7 +2562,8 @@ static int launchctl_schedule_plist(const char *exec_path, enum schedule_priorit
 		lock_file_timeout_ms = 150;
 
 	fd = hold_lock_file_for_update_timeout(&lk, filename, LOCK_DIE_ON_ERROR,
-					       lock_file_timeout_ms);
+					       lock_file_timeout_ms,
+					       LOCKFILE_PID_GC);
 
 	/*
 	 * Does this file already exist? With the intended contents? Is it
@@ -3372,7 +3374,8 @@ static int update_background_schedule(const struct maintenance_start_opts *opts,
 	struct lock_file lk;
 	char *lock_path = xstrfmt("%s/schedule", the_repository->objects->sources->path);
 
-	if (hold_lock_file_for_update(&lk, lock_path, LOCK_NO_DEREF) < 0) {
+	if (hold_lock_file_for_update(&lk, lock_path, LOCK_NO_DEREF,
+				      LOCKFILE_PID_GC) < 0) {
 		if (errno == EEXIST)
 			error(_("unable to create '%s.lock': %s.\n\n"
 			    "Another scheduled git-maintenance(1) process seems to be running in this\n"

builtin/sparse-checkout.c

@@ -341,7 +341,8 @@ static int write_patterns_and_update(struct repository *repo,
 	if (safe_create_leading_directories(repo, sparse_filename))
 		die(_("failed to create directory for sparse-checkout file"));
 
-	hold_lock_file_for_update(&lk, sparse_filename, LOCK_DIE_ON_ERROR);
+	hold_lock_file_for_update(&lk, sparse_filename, LOCK_DIE_ON_ERROR,
+				  LOCKFILE_PID_OTHER);
 
 	result = update_working_directory(repo, pl);
 	if (result) {

bundle.c

@@ -520,7 +520,8 @@ int create_bundle(struct repository *r, const char *path,
 		bundle_fd = 1;
 	else
 		bundle_fd = hold_lock_file_for_update(&lock, path,
-						      LOCK_DIE_ON_ERROR);
+						      LOCK_DIE_ON_ERROR,
+						      LOCKFILE_PID_OTHER);
 
 	if (version == -1)
 		version = min_version;