Re: [PATCH v2 1/1] gitfaq: append the 'Common Issues' section

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

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

>+ [[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(if
>+ 	any).

You push changes to a repository.
You fetch changes from a repository.

Hence, "a location, which you push changes to, as well as fetch new
changes from, if any."  But a lot more people fetch from repositories
than push to repositories, so "a location, which you fetch changes from,
as well as push your changes to." may be easier to follow by audiences.

In any case there is one crucial and precious thing in what you
wrote here.  A remote is a name for *A* location, even if you have
two URLs (i.e. one used for fetching from, and another used for
pushing to).  They are to name logically the same place, only the
way you reach may be different.  For example, you may have an
unauthenticated https:// URL for fetching, while the URL you use to
the repository may be ssh:// URL.  But the important point is that
these URLs are about the same repository---if you push over ssh://
URL your changes, you would be able to see the changes over https://
URL that you use for fetching.

>+      There might be different circumstances in which one
>+ 	might need to change the remote:

Sure.

>+ 		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>`.

Yes, this truly is "changing" the old one by replacing its old URL
with a new URL.

>+ 		2. One might want to have two different remotes for
>+ 		fetching and pushing; this generally happens in case
>+ 		of triangular workflows.  In this case, it is
>+ 		advisable to create a separate remote just for
>+ 		fetching/pushing.

Yes, by definition, triangular is about fetching from somebody else
and publishing to your own place for others to fetch, so you'd need
two remotes, as you are not talking with a single repository.

But I find your phrasing quite confusing.

"advisable to have two remotes, one for fetching and the other for
pushing" would probably be a lot more correct.

And I can understand why you did not write so, and instead ended up
with your version.  In order to reach the goal of having two (one
for push and one for fetch), you would "create a separate remote" as
you are likely to already have one for one direction (in other
words, you didn't want to say "advisable to create two remotes").

You wrote "create a separate remote just for fetching/pushing" and
made the direction of the new one vague, because you do not know if
that existing one is for fetching or pushing,

But I suspect that all of the above would not be as clear to those
who need their questions answered as to somebody like me who knows
what you want to say already.  And you do not want to explain things
in a way that only is understood by experts.  How about rephrasing
the above more like so?

	2. One may want to fetch from one repository and push to
	anther repository---this is often called a "triangular"
	workflow.  As you'd probably have one remote that you use
	for fetching already created when you cloned the project,
	you would want to create a separate remote to record the URL
	you push to.

>+ But, another way can be to change
>+ 		the push url using the `--push` option in the `git
>+ 		set-url` command.

Do not recommend this when you describe a triangular workflow; it is
confusing to readers.  Keeping separate fetch and push URLs for a
single remote is not triangular.  

Describe it separately as a different use case, e.g.

	3. You may want to push to a repository over a network
	protocol different from the one you use to fetch from the
	repository.  Perhaps you want unauthenticated https:// URL
	for fetching from, and use ssh:// URL when you push to, the
	same remote.  In such a case, ...

Other than the above nits I picked, overall it is a good idea to
raise this question in the FAQ, I would think.

Thanks.