add documentation for writing config files

Replace TODO introduced in commit 9c3c22 with documentation
explaining Git config API functions for writing configuration
files.

Signed-off-by: Tanay Abhra <tanayabh@gmail.com>
Reviewed-by: Matthieu Moy <Matthieu.Moy@grenoble-inp.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
git-push: fix link in man page

Signed-off-by: Tony Finch <dot@dotat.at>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Merge branch 'ta/doc-config'

* ta/doc-config:
  add documentation for writing config files
Merge branch 'tf/maint-doc-push'

* tf/maint-doc-push:
  git-push: fix link in man page
Git 2.1.0-rc1

Signed-off-by: Junio C Hamano <gitster@pobox.com>
RelNotes: no more check_ref_format micro-optimization

Signed-off-by: Junio C Hamano <gitster@pobox.com>
various contrib: Fix links in man pages

Inspired by 2147fa7e (2014-07-31 git-push: fix link in man page),
I grepped through the whole tree searching for 'gitlink:' occurrences.

Signed-off-by: Stefan Beller <stefanbeller@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Release notes: grammatical fixes

Signed-off-by: Marc Branchaud <marcnarc@xiplink.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Merge branch 'mb/relnotes-2.1'

* mb/relnotes-2.1:
  Release notes: grammatical fixes
  RelNotes: no more check_ref_format micro-optimization
Makefile: drop USE_GETTEXT_SCHEME from GIT-CFLAGS

This variable is used only by shell scripts, not by C
programs. It was originally included in GIT-CFLAGS as part
of ad17ea7 (add a Makefile switch to avoid gettext
translation in shell scripts, 2012-01-23), in an attempt to
trigger rebuilding when the variable changed.

However, shell scripts do not respect GIT-CFLAGS. Later,
e4dd89a (Makefile: update scripts when build-time parameters
change, 2012-06-20) introduced a separate GIT-SCRIPT-DEFINES
to accomplish this, which also included USE_GETTEXT_SCHEME.
We can drop the redundant and useless mention in GIT-CFLAGS.
Makefile: fix git-instaweb dependency on gitweb

We build git-instaweb if NO_PERL is not defined, and it in
turns depends on "gitweb", which causes us to descend into
the gitweb subdir and recursively invoke make. But because
gitweb is marked as .PHONY, this forces a rebuild of
git-instaweb every time we run make.

We can drop the dependency of git-instaweb on gitweb.
However, that means we do not recurse into "gitweb" at all,
so we have to add back in the dependency to "all".

Note that the other subdirectories (like git-gui/ or perl/)
are handled directly as build commands of "all", and we
could simply do the same thing here. However, this patch
keeps "gitweb" as a target so that "make gitweb" continues
to work, in case anybody is using that.
Makefile: introduce make-var helper function

It's a common pattern in our Makefile to echo some make
variables into a file, but only if they are different from a
previous run. This sentinel file can then be used as a
dependency to trigger rebuilds when the make variable
changes.

The code to do this is a bit ugly and repetetive; let's
factor it out into a reusable function.

Note that this relies on the "call" and "eval" functions of
GNU make. We previously avoided using "call", as explained
in 39c015c (Fixes for ancient versions of GNU make,
2006-02-18). However, it has been 8 years since then, so
perhaps its use is acceptable now.

The "call" function dates back to GNU make 3.77.90
(1997-07-21). The "eval" function dates back to 3.80
(2002-07-08).

If it's still a problem to use these functions, we can
do similar meta-programming with something like:

	include magic.mak
	magic.mak:
		./generate-magic-rules >$@+
		mv $@+ $@

where the rules are generated by a shell (or other) script.
Makefile: use tempfile/mv strategy for GIT-*

We create GIT-CFLAGS and related files by echoing into a
shell redirection. It's possible for an error to cause the
file to end up empty or truncated. In theory, this could
cause us to later make an incorrect comparison of the file
contents to a Makefile variable, and avoid rebuilding some
dependencies.

In practice, this is very unlikely to happen, as the
followup run would have to have changed the variable to
match the truncation exactly. However, it is good hygiene to
use our usual tempfile + mv trick to make sure that the file
is created atomically.
Makefile: prefer printf to echo for GIT-*

When we write Makefile variables to a sentinel file, we use
"echo" to do so. Since we are writing arbitrary data which
may contain backslash escapes (particularly with file paths
on Windows), echo may or may not expand those escapes,
depending on which shell is in use.

During the next run of "make", we check the sentinel file to
see if it is different than the Makefile variable. If
escapes were expanded, then we will erroneously think it
changed and trigger a rebuild. You can see this easily by
running:

  make prefix='foo\bar'

multiple times; it will re-build some files repeatedly.
Makefile: store GIT-* sentinel files in MAKE/

The Makefile creates files like GIT-CFLAGS to keep track of
the make variables used in the last build. We have a number
of these files now, all starting with GIT-*. Let's move them
into their own subdirectory, which has two advantages:

  1. It's less clutter in the main directory.

  2. Each file needs to be marked separately in .gitignore.
     With a subdirectory, we can easily mark them all with a
     wildcard (we cannot do a wildcard for GIT-* because
     of precious files like GIT-VERSION-GEN).

This patch moves all of the generated GIT-* files into
MAKE/*, with one exception: GIT-VERSION-FILE. This could be
moved along with the rest, but there is a reasonable chance
that there are some out-of-tree scripts that may peek at it
(whereas things like GIT-CFLAGS are purely internal, and we
update all internal references).
Makefile: always create files via make-var

If we are trying to store an empty sentinel value for a
make-var, we would consider a missing file the same as an
empty variable. E.g., repeatedly running:

  make GIT_USER_AGENT=

will not create MAKE/USER-AGENT at all if it does not exist,
and subsequent make invocations will force a rebuild. This
is not generally a problem in practice, since most of the
files always have some boilerplate (even LDFLAGS, because it
is formed with "+=", will have a stray space in it). But
this does fix the rare case, and future-proofs us as we add
more similar variables.
Makefile: introduce sq function for shell-quoting

Since we have recently abolished the prohibition on $(call)
in our Makefile, we can use it to factor out the repeated
shell-quoting we do. There are two upsides:

  1. It is much more readable than inline calls to
     $(subst ','\'').

  2. It is short enough that we can do away with the _SQ
     variants of many variables (note that we do not do this
     just yet, as there is a little more cleanup needed
     first).
Makefile: add c-quote helper function

We have to c-quote strings coming from Makefile variables
when we pass them to the compiler via "-D". Now that we can
use $(call) in our Makefile, we can factor out the quoting
to make things easier to read. We can also apply it more
consistently, as there were many spots that should have been
C-quoting but did not. For example:

  make prefix='foo\bar'

would produce an exec_cmd.o with a broken prefix.
Makefile: drop *_SQ variables

Now that all uses of the SQ variables have been dropped, we
can stop setting the variables.
Makefile: auto-build C strings from make variables

We already insert the values of some make variables into
files in MAKE/*. We can therefore build a simple pattern
rule for converting such a value into a C string in a header
file, which can then be included and used as normal.

The new system is demonstrated on version.c, where it can
replace the use of "-D" on the command-line. Note that we
still have to manually specify a dependency in the
Makefile. In an ideal world, we would auto-detect the header
dependency; however, there are two holdups:

  1. We cannot rely on having automatic header dependency
     generation on all platforms.

  2. Even when we do generate the dependencies, we rely on
     being able to compile the file once, which means our
     system cannot handle generated headers without a manual
     dependency to bootstrap it.