credentials: add "getpass" helper

This just does the normal "ask on the terminal, or use
GIT_ASKPASS" logic that we already do. But it's useful for
writers of third-party helpers. See the documentation for an
example.

Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

.gitignore

@@ -33,6 +33,7 @@
 /git-credential-cache
 /git-credential-cache--daemon
 /git-credential-store
+/git-credential-getpass
 /git-cvsexportcommit
 /git-cvsimport
 /git-cvsserver

Documentation/git-credential-getpass.txt

@@ -0,0 +1,58 @@
+git-credential-getpass(1)
+=========================
+
+NAME
+----
+git-credential-getpass - helper to request credentials from a user
+
+SYNOPSIS
+--------
+[verse]
+git credential-getpass
+
+DESCRIPTION
+-----------
+
+This command requests credentials from the user using git's "default"
+scheme, including asking via the terminal and respecting the
+`GIT_ASKPASS` environment variable; see linkgit:gitcredentials[7] for a
+complete description. The helpers are provided on stdout using git's
+credential helper protocol.
+
+There is no point in using this program as a credential helper by
+itself; it is exactly equivalent to git's behavior when no helper is
+configured.
+
+However, writers of third-party helpers may want to invoke this program
+to simulate git's behavior.
+
+EXAMPLES
+--------
+
+Here's a simple, silly example of a helper that stores credentials on
+disk (similar to linkgit:git-credential-store[1]), and how it could use
+the `getpass` helper.
+
+-------------------------------------------
+#!/bin/sh
+
+STORAGE=$HOME/.credentials
+
+for i in "$@"; do
+	case "$i" in
+	--unique=*)
+		unique=${i#--unique=} ;;
+	esac
+done
+
+if ! test -e "$STORAGE/$unique"; then
+	mkdir -m 0700 "$STORAGE"
+	git credential-getpass "$@" >"$STORAGE/$unique"
+fi
+
+cat "$STORAGE/$unique"
+-------------------------------------------
+
+GIT
+---
+Part of the linkgit:git[1] suite

Makefile

@@ -423,6 +423,7 @@ PROGRAM_OBJS += sh-i18n--envsubst.o
 PROGRAM_OBJS += credential-cache.o
 PROGRAM_OBJS += credential-cache--daemon.o
 PROGRAM_OBJS += credential-store.o
+PROGRAM_OBJS += credential-getpass.o
 
 PROGRAMS += $(patsubst %.o,git-%$X,$(PROGRAM_OBJS))
 

credential-getpass.c

@@ -0,0 +1,37 @@
+#include "cache.h"
+#include "credential.h"
+#include "parse-options.h"
+#include "string-list.h"
+
+int main(int argc, const char **argv)
+{
+	const char * const usage[] = {
+		"git credential-getpass [options]",
+		NULL
+	};
+	struct credential c = { NULL };
+	int reject = 0;
+	struct option options[] = {
+		OPT_BOOLEAN(0, "reject", &reject,
+			    "reject a stored credential"),
+		OPT_STRING(0, "username", &c.username, "name",
+			   "an existing username"),
+		OPT_STRING(0, "description", &c.description, "desc",
+			   "human-readable description of the credential"),
+		OPT_STRING(0, "unique", &c.unique, "token",
+			   "a unique context for the credential"),
+		OPT_END()
+	};
+
+	argc = parse_options(argc, argv, NULL, options, usage, 0);
+	if (argc)
+		usage_with_options(usage, options);
+
+	if (reject)
+		return 0;
+
+	credential_getpass(&c);
+	printf("username=%s\n", c.username);
+	printf("password=%s\n", c.password);
+	return 0;
+}