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
sha1_name: refactor upstream_mark

We will be adding new mark types in the future, so separate
the suffix data from the logic.
branch_get: return early on error

Right now we simply check if "ret" is valid before doing
further processing. As we add more processing, this will
become more and more cumbersome. Instead, let's just check
whether "ret" is invalid and return early with the error.
branch_get: provide per-branch pushremote pointers

When a caller uses branch_get to retrieve a "struct branch",
they get the per-branch remote name and a pointer to the
remote struct. However, they have no way of knowing about
the per-branch pushremote from this interface.

Let's expose that information via fields similar to
"remote" and "remote_name".

We have to do a little refactoring around the configuration
reading here. Instead of pushremote_name being its own
allocated string, it instead becomes a pointer to one of:

  1. The pushremote_name of the current branch, if
     configured.

  2. The globally configured remote.pushdefault, which we
     store separately as pushremote_config_default.

We can then set the branch's "pushremote" field by doing the
normal sequence of config fallback.
implement @{publish} shorthand

In a triangular workflow, you may have a distinct
@{upstream} that you pull changes from, but publish by
default (if you typed "git push") to a different remote (or
a different branch on the remote). It may sometimes be
useful to be able to quickly refer to that publishing point
(e.g., to see which changes you have that have not yet been
published).

This patch introduces the <branch>@{publish} shorthand (or
"@{pu}" to be even shorter). It refers to the tracking
branch of the remote branch to which you would push if you
were to push the named branch. That's a mouthful to explain,
so here's an example:

  $ git checkout -b foo origin/master
  $ git config remote.pushdefault github
  $ git push