| Message ID | 20200429093811.8475-4-shouryashukla.oo@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [v4,1/4] gitfaq: files in .gitignore are tracked | expand |
On Wed, Apr 29, 2020 at 2:38 AM Shourya Shukla <shouryashukla.oo@gmail.com> wrote: > > 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 | 20 ++++++++++++++++++++ > 1 file changed, 20 insertions(+) > > diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt > index 6f32846e3d..e091513639 100644 > --- a/Documentation/gitfaq.txt > +++ b/Documentation/gitfaq.txt > @@ -253,6 +253,26 @@ way of cloning it in lesser space?:: > Any entity which has not been cloned to save space can be cloned > on-demand. 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). 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. > + Fetching does not have any immediate effects on the local > + repository. Maybe change that last sentence to "Fetching does not modify the current branch"? The local repository certainly gets bigger, and the remote tracking branches are updated as well as their reflogs, and it might trigger a gc, all of which sound like immediate effects to me. > + > + A pull is a wrapper for a fetch and merge. This means that doing ...for a fetch and merge or a fetch and rebase. This means... > + a `git pull` will not only fetch the changes made upstream but > + integrate them as well with our local repository. The merge may ...with our current branch. The merge or rebase... > + go smoothly or have merge conflicts depending on the case. A pull > + does not allow you to review any changes made upstream but rather > + merge those changes on their own. I don't understand this last sentence. You can definitely review changes made upstream after a pull; e.g. git log @{u}@{1}..@{u} > ++ > +This is the reason why it is sometimes advised to fetch the changes > +first and then merge them accordingly because not every change might > +be of utility to the user. I don't understand the purpose of this paragraph.
Elijah Newren <newren@gmail.com> writes: >> + go smoothly or have merge conflicts depending on the case. A pull >> + does not allow you to review any changes made upstream but rather >> + merge those changes on their own. > > I don't understand this last sentence. You can definitely review > changes made upstream after a pull; e.g. git log @{u}@{1}..@{u} > >> ++ >> +This is the reason why it is sometimes advised to fetch the changes >> +first and then merge them accordingly because not every change might >> +be of utility to the user. > > I don't understand the purpose of this paragraph. Readers who need to resort to a FAQ will be at loss when told "it is sometimes advised to...", as they do not know enough to judge if the advice applies to their situation themselves. Don't we have a workflow document? Not the one that documents the workflow I use to maintain this project, but outlines various ways different projects work, describing centralized, triangular, merging and rebasing, etc.? I do not think this single entry belongs to a FAQ list that gives simple answers to common questions without people having to think. Similar to the "merge or rebase?" question (not part of this series), it belongs to "workflow guide", "concepts manual", and "tutorial" kind of document, I would think.
On 29/04 08:56, Elijah Newren wrote: > > +[[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). 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. > > + Fetching does not have any immediate effects on the local > > + repository. > > Maybe change that last sentence to "Fetching does not modify the > current branch"? The local repository certainly gets bigger, and the > remote tracking branches are updated as well as their reflogs, and it > might trigger a gc, all of which sound like immediate effects to me. I meant changes in terms of the user's code. Yep you are right, I need to be precise here. > > + > > + A pull is a wrapper for a fetch and merge. This means that doing > > ...for a fetch and merge or a fetch and rebase. This means... > > > + a `git pull` will not only fetch the changes made upstream but > > + integrate them as well with our local repository. The merge may > > ...with our current branch. The merge or rebase... > > > + go smoothly or have merge conflicts depending on the case. A pull > > + does not allow you to review any changes made upstream but rather > > + merge those changes on their own. > > I don't understand this last sentence. You can definitely review > changes made upstream after a pull; e.g. git log @{u}@{1}..@{u} I meant that the pull will apply the changes right away and one does not get the chance to review what is being applied before it has been applied (something a fetch does). I need to be more clear here, understood. > > ++ > > +This is the reason why it is sometimes advised to fetch the changes > > +first and then merge them accordingly because not every change might > > +be of utility to the user. > > I don't understand the purpose of this paragraph. I intended to emphasise the difference between a fetch and a pull; the fact that fetch just brings in the changes from the remote and doesnot apply them to our code/files right away, while a pull does so. Also, a nit but, we are supposed to use 1 SP or 2 SP after a full stop(.)? In India we use 1 SP, is it different in other countries?
Hi Shourya, On Fri, May 1, 2020 at 11:57 PM Shourya Shukla <shouryashukla.oo@gmail.com> wrote: > > On 29/04 08:56, Elijah Newren wrote: > > > +[[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). 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. > > > + Fetching does not have any immediate effects on the local > > > + repository. > > > > Maybe change that last sentence to "Fetching does not modify the > > current branch"? The local repository certainly gets bigger, and the > > remote tracking branches are updated as well as their reflogs, and it > > might trigger a gc, all of which sound like immediate effects to me. > > I meant changes in terms of the user's code. Yep you are right, I need > to be precise here. > > > > + > > > + A pull is a wrapper for a fetch and merge. This means that doing > > > > ...for a fetch and merge or a fetch and rebase. This means... > > > > > + a `git pull` will not only fetch the changes made upstream but > > > + integrate them as well with our local repository. The merge may > > > > ...with our current branch. The merge or rebase... > > > > > + go smoothly or have merge conflicts depending on the case. A pull > > > + does not allow you to review any changes made upstream but rather > > > + merge those changes on their own. > > > > I don't understand this last sentence. You can definitely review > > changes made upstream after a pull; e.g. git log @{u}@{1}..@{u} > > I meant that the pull will apply the changes right away and one does not > get the chance to review what is being applied before it has been > applied (something a fetch does). I need to be more clear here, > understood. > > > > ++ > > > +This is the reason why it is sometimes advised to fetch the changes > > > +first and then merge them accordingly because not every change might > > > +be of utility to the user. > > > > I don't understand the purpose of this paragraph. > > I intended to emphasise the difference between a fetch and a pull; the > fact that fetch just brings in the changes from the remote and doesnot > apply them to our code/files right away, while a pull does so. So, perhaps we can shorten all three paragraphs to something like the following? 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. > Also, a nit but, we are supposed to use 1 SP or 2 SP after a full > stop(.)? In India we use 1 SP, is it different in other countries? Ah, the never ending spacing debate... There may be variation country-to-country, but I doubt it's country specific. It's more a raging debate based on the fact that "official" rules have changed multiple times, old habits die hard, different contexts exist for different audiences, and various other wrinkles. ("official" needs quotes because it's not clear who the authority on publishing, writing, or style is. There are multiple out there. But even if you pick a fairly commonly quoted authority, such as the Chicago manual of style, they've had at least three different rules for how much space to use after the full stop over time.) If you use a typesetting program like LaTeX, the amount of space you use in the source is irrelevant as the target will automatically be generated with the right amount according to whatever ruleset is in play (you just need to be careful to specify when periods are used in abbreviations versus at ends of sentences). But if you are using a WYSIWYG document or a plain text document for both generation and consumption of the information, then some kind of rule is needed. Fixed width versus proportional fonts also matter. The two space rule arose in the age of typewriters, which came about during the era when larger spaces between sentences was the typesetting rule, and was translated into a two-space rule. Many of the one-space rules and rule changes arose among those assuming everything would be using variable width fonts[1]. Unless you're crazy[2], source code remains fixed width and emails on mailing lists like git@vger often are too (whenever someone sends a table as part of a commit message or just in discussion, attempting to read it in a proportional font is impossible; gmail is atrocious and a crime against humanity here but luckily I can just go over to lore.kernel.org/git to read the emails in a fixed width font). There does seem to be emerging consensus among many style guides (which come from those that just outright assume that variable width fonts are the only kind that exist anymore) that just one space should be used, though it appears to be at least partially because one space is easy for editors to enforce[3]. (Switching from two spaces to one is a simple search and replace, whereas switching from one space to two is really hard because you have to know whether a period ends an abbreviation like "Dr." or ends a sentence.) The emerging style rules also exist despite a (recent-ish) study showing that two spaces slightly aids reading speed[4]. Personally, I still remember using a single space after sentences, and my dad standing over my shoulder and letting me know that it was WRONG to do that and that sentences should be followed by two spaces. 25 years later, it's an ingrained habit. But the fact that I spend most of my time in an environment that most the style guides presume no longer exists or is used (namely fixed width fonts, as found with source code), means that I've got a good argument that the conventions used back in the days of typewriters are the ones that are actually correct within my context. Plus there's actually a scientific study that just conveniently happens to match my habit, so now I can claim that I've been right all along these past 25 years; in the end, that's all that really matters anyway. ;-) [1] https://slate.com/technology/2011/01/two-spaces-after-a-period-why-you-should-never-ever-do-it.html [2] https://twitter.com/rob_pike/status/567476552187641856?lang=en [3] https://cmosshoptalk.com/2020/03/24/one-space-or-two/ [4] https://link.springer.com/article/10.3758/s13414-018-1527-6
Elijah Newren <newren@gmail.com> writes: >> Also, a nit but, we are supposed to use 1 SP or 2 SP after a full >> stop(.)? In India we use 1 SP, is it different in other countries? > > Ah, the never ending spacing debate... > > There may be variation country-to-country, but I doubt it's country > specific. It's more a raging debate based on the fact that "official" > rules have changed multiple times, old habits die hard, different > contexts exist for different audiences, and various other wrinkles. https://www.theverge.com/2020/4/24/21234170 ;-) Since very old days of print media until now and well into the future, readers want to see longer whitespace after the end of each sentence than whitespace between words. Behaviour of programs that that take your "text file" as its input and produces rendered output differ. Some ignore the number of spaces after the full-stop and "do the right thing" its output (that's the norm for typesetting systems), and others want to see only one space there, and leaves more swhitespace than optimal if you put two or more (which is often how WYSIWYG word processors work). The ideal would be to keep both the source text file and rendered output pleasant to the eyes, and that means we type two spaces after the end of a sentence in the source (which is meant to be read in monospace text) and we avoid formatting programs that break (i.e. produce more spaces than desirable) when fed more than one space after each sentence (otherwise, we would be forced to use only one space and hurt our eyes). I think our arrangement to go from source text through AsciiDoc or Asciidoctor to manpage or XHTML produces the right output with two spaces, so we are good.
diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt index 6f32846e3d..e091513639 100644 --- a/Documentation/gitfaq.txt +++ b/Documentation/gitfaq.txt @@ -253,6 +253,26 @@ way of cloning it in lesser space?:: Any entity which has not been cloned to save space can be cloned on-demand. 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). 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. + Fetching does not have any immediate effects on the local + repository. + + A pull is a wrapper for a fetch and merge. This means that doing + a `git pull` will not only fetch the changes made upstream but + integrate them as well with our local repository. The merge may + go smoothly or have merge conflicts depending on the case. A pull + does not allow you to review any changes made upstream but rather + merge those changes on their own. ++ +This is the reason why it is sometimes advised to fetch the changes +first and then merge them accordingly because not every change might +be of utility to the user. + Hooks -----
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 | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+)