Re: [PATCH v3 2/4] gitfaq: changing the remote of a repository

[Junio C Hamano <gitster@pobox.com>]

Shourya Shukla <shouryashukla.oo@gmail.com> writes:

> Add issue in 'Common Issues' section which addresses the problem of
> changing the remote of a repository, covering various cases in which
> one might want to change the remote and the ways to do the same.
>
> Signed-off-by: Shourya Shukla <shouryashukla.oo@gmail.com>
> ---
>  Documentation/gitfaq.txt | 31 +++++++++++++++++++++++++++++++
>  1 file changed, 31 insertions(+)

Again, I think this belongs to Documentation/git-remote.txt; unlike
the ".gitignore" one, however, the existing description is heavily
concentrated on "what happens when X is set to Y?" and does not
answer "why would I want to set X to Y in the first place?" very
much.  And the text below you have is a good thing to teach anybody
who learns "git-remote".  

So how about clarifying the existing page, perhaps its DISCUSSION
section (which currently talks only about "how to add a remote, and
configure" without discussing "why would I want to add a remote, set
a URL and/or a pushURL to it") with what you have, and trim the
description here in the FAQ file to the minimum and refer to the
page instead?

> diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
> index 96767e7c75..13d37f96af 100644
> --- a/Documentation/gitfaq.txt
> +++ b/Documentation/gitfaq.txt
> @@ -244,6 +244,37 @@ I asked Git to ignore various files, yet they are still tracked::
>  	category, it is advised to use `git rm --cached <file>` as well as
>  	add these files/paths in the `.gitignore`.
>  
> +[[changing-remote-of-the-repository]]
> +I want to change the remote of my repository. How do I do that?::
> +	A remote is an identifier for a location to which Git pushes your
> +	changes as well as fetches any new changes from (if any). There
> +	might be different circumstances in which one might need to change
> +	the remote:
> +
> +		1. One might want to update the URL of their remote; in that
> +		   case, the command to use is, `git remote set-url <name> <newurl>`.
> +
> +		2. One might want to have two different remotes for fetching
> +		   and pushing; this generally happens in case of triangular
> +		   workflows: one fetches from one repository and pushes to
> +		   another. In this case, it is advisable to have separate
> +		   remotes for fetching and pushing. But, another way can be
> +		   to change the push URL using the `--push` option in the
> +		   `git set-url` command.
> +
> +		3. One might want to push changes to a network protocol
> +		   different from the one they fetch from. For instance,
> +		   one may be using an unauthenticated http:// URL for
> +		   fetching from a repository and use an ssh:// URL when
> +		   you push via the same remote. In such a case, one can
> +		   change the 'push' URL of the same remote using the `--push`
> +		   option in `git remote set-url`. Now, the same remote will
> +		   have two different kinds of URLs (http and ssh) for fetching
> +		   and pulling.
> ++
> +One can list the remotes of a repository using `git remote -v` command.
> +The default name of a remote is 'origin'.
> +
>  Hooks
>  -----