Re: [PATCH v5 4/4] gitfaq: fetching and pulling a repository
On Sun, May 3, 2020 at 10:42 PM Shourya Shukla <shouryashukla.oo@gmail.com> wrote:
Show 33 quoted lines
>
> Add an issue in 'Common Issues' section which addresses the confusion
> between performing a 'fetch' and a 'pull'.
>
> Signed-off-by: Shourya Shukla <shouryashukla.oo@gmail.com>
> ---
> Documentation/gitfaq.txt | 16 ++++++++++++++++
> 1 file changed, 16 insertions(+)
>
> diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
> index 5dfbb32089..04ea7be99f 100644
> --- a/Documentation/gitfaq.txt
> +++ b/Documentation/gitfaq.txt
> @@ -255,6 +255,22 @@ way of cloning it in lesser space?::
> presumes that the user has an always-on network connection to the
> original repository). See linkgit:partial-clone[1].
>
> +[[fetching-and-pulling]]
> +How do I know if I want to do a fetch or a pull?::
> + A fetch brings in the latest changes made upstream (i.e., the
> + remote repository we are working on) without modifying the current
> + branch or the working tree. This allows us to inspect
> + the changes made upstream and integrate all those changes (if
> + and only if we want to) or only cherry pick certain changes.
> +
> + A pull is a wrapper for a fetch and merge/rebase. This means that
> + doing a `git pull` will not only fetch the changes made upstream
> + but integrate them immediately with our current branch too. The
> + merge/rebase may go smoothly or have merge conflicts depending
> + on the case. Hence, a pull does not give the user a chance to
> + review changes before applying them to their local repository/current
> + branch.
> +
So a few issues; elsewhere in this thread, Junio said:
We should strive to (1) make sure any FAQ entry can have a pointer
to more comprehensive and canonical documentation, and (2) an FAQ
entry with such a pointer does not consume more than one paragraph,
say no more than 5 lines.* This answer is multiple paragraphs and 12 lines.
* The answer is fairly repetitive (e.g. why add "if and only if we
want to"; isn't that already covered by "allows us to"?). You also
bring up inspecting/reviewing the changes multiple times.
* This brings up cherry-picking in a really awkward way that seems to
be suggesting or at least condoning what sounds like a very broken
workflow. (If it's your upstream, why are you only cherry-picking
changes from it? You're going to get divergent history and the next
merge will end up with multiple copies of the commits. If it's
something you only cherry-pick from, it sounds like it isn't intended
to be an upstream but something else.)
* This side-tracks into the results of a merge or rebase; why do we
need to mention that it can go smoothly or have conflicts at this
point?
How about the five line version I suggested earlier:
A fetch stores a copy of the latest changes from the remote repository, without modifying the working tree or current branch. You can then at your leisure inspect, merge, rebase on top of, or ignore the upstream changes. A pull consists of a fetch followed immediately by either a merge or rebase.
You could optionally also add a link to the git-pull documentation (which incidentally also answers the original question in the first four sentences of its description).
Shourya Shukla
