[PATCH v4 1/4] gitfaq: files in .gitignore are tracked

[PATCH v4 1/4] gitfaq: files in .gitignore are tracked

[Shourya Shukla]

Add issue in 'Common Issues' section which addresses the problem of
Git tracking files/paths mentioned in '.gitignore'.

Signed-off-by: Shourya Shukla <shouryashukla.oo@gmail.com>
---
 Documentation/gitfaq.txt | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
index 1cf83df118..b1e758ffd1 100644
--- a/Documentation/gitfaq.txt
+++ b/Documentation/gitfaq.txt
@@ -223,6 +223,15 @@ a file checked into the repository which is a template or set of defaults which
 can then be copied alongside and modified as appropriate.  This second, modified
 file is usually ignored to prevent accidentally committing it.
 
+[[files-in-.gitignore-are-tracked]]
+I asked Git to ignore various files, yet they are still tracked::
+	A `gitignore` file specifies intentionally untracked files
+	that Git should ignore. Files already tracked by Git are
+	not affected. See linkgit:gitignore[5] for details.
+	To ignore and untrack the files appearing in the staging are
+	it is advised to use `git rm --cached <file>`as well as make
+	the file pattern is mentioned in the '.gitignore'.
+
 Hooks
 -----
 
-- 
2.26.2

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

[Shourya Shukla]

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 | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
index b1e758ffd1..7d294306f9 100644
--- a/Documentation/gitfaq.txt
+++ b/Documentation/gitfaq.txt
@@ -232,6 +232,17 @@ I asked Git to ignore various files, yet they are still tracked::
 	it is advised to use `git rm --cached <file>`as well as make
 	the file pattern is mentioned 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 URL (see linkgit:git-remote[1]). To change the remote URL
+	one may use: git remote set-url <name> <newurl>
++
+One can list the remotes of a repository using `git remote -v` command.
+The default name of a remote is 'origin'.
+
 Hooks
 -----
 
-- 
2.26.2

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

[Elijah Newren]

On Wed, Apr 29, 2020 at 2:38 AM Shourya Shukla
<shouryashukla.oo@gmail.com> wrote:
>
> 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 | 11 +++++++++++
>  1 file changed, 11 insertions(+)
>
> diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
> index b1e758ffd1..7d294306f9 100644
> --- a/Documentation/gitfaq.txt
> +++ b/Documentation/gitfaq.txt
> @@ -232,6 +232,17 @@ I asked Git to ignore various files, yet they are still tracked::
>         it is advised to use `git rm --cached <file>`as well as make
>         the file pattern is mentioned 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 URL (see linkgit:git-remote[1]). To change the remote URL
> +       one may use: git remote set-url <name> <newurl>
> ++
> +One can list the remotes of a repository using `git remote -v` command.
> +The default name of a remote is 'origin'.

Looks good to me.  :-)

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

[Junio C Hamano]

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 | 11 +++++++++++
>  1 file changed, 11 insertions(+)
>
> diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
> index b1e758ffd1..7d294306f9 100644
> --- a/Documentation/gitfaq.txt
> +++ b/Documentation/gitfaq.txt
> @@ -232,6 +232,17 @@ I asked Git to ignore various files, yet they are still tracked::
>  	it is advised to use `git rm --cached <file>`as well as make
>  	the file pattern is mentioned 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 URL (see linkgit:git-remote[1]). To change the remote URL
> +	one may use: git remote set-url <name> <newurl>
> ++
> +One can list the remotes of a repository using `git remote -v` command.
> +The default name of a remote is 'origin'.

With the trimming, it got a lot easier to follow.  

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.

It may be tempting to cram as much information as it comes to your
head as possible when writing a FAQ document, but for those who need
FAQ list, a list of pointers with clear and concise summary is more
helpful.

Thanks.

[PATCH v4 3/4] gitfaq: shallow cloning a repository

[Shourya Shukla]

Add issue in 'Common issue' section which covers issues with cloning
large repositories. Use partial cloning to selectively clone the
repository.

Signed-off-by: Shourya Shukla <shouryashukla.oo@gmail.com>
---
I wanted to ask why is there no mention of partial cloning in
the 'git-clone' documentation? Is it because it is an experimental
feature?

 Documentation/gitfaq.txt | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
index 7d294306f9..6f32846e3d 100644
--- a/Documentation/gitfaq.txt
+++ b/Documentation/gitfaq.txt
@@ -243,6 +243,16 @@ I want to change the remote of my repository. How do I do that?::
 One can list the remotes of a repository using `git remote -v` command.
 The default name of a remote is 'origin'.
 
+[[shallow-cloning]]
+The repository I am trying to clone is too big. Is there an alternative
+way of cloning it in lesser space?::
+	A good way to save up space when cloning a repository is
+	by using `partial clones`. A partial clone will clone the
+	full history of the repository but will skip out the entities
+	specified by the `--filter` option one uses in `git clone`.
+	Any entity which has not been cloned to save space can be cloned
+	on-demand. See linkgit:partial-clone[1].
+
 Hooks
 -----
 
-- 
2.26.2

Re: [PATCH v4 3/4] gitfaq: shallow cloning a repository

[Elijah Newren]

On Wed, Apr 29, 2020 at 2:38 AM Shourya Shukla
<shouryashukla.oo@gmail.com> wrote:
>
> Add issue in 'Common issue' section which covers issues with cloning
> large repositories. Use partial cloning to selectively clone the
> repository.
>
> Signed-off-by: Shourya Shukla <shouryashukla.oo@gmail.com>
> ---
> I wanted to ask why is there no mention of partial cloning in
> the 'git-clone' documentation? Is it because it is an experimental
> feature?
>
>  Documentation/gitfaq.txt | 10 ++++++++++
>  1 file changed, 10 insertions(+)
>
> diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
> index 7d294306f9..6f32846e3d 100644
> --- a/Documentation/gitfaq.txt
> +++ b/Documentation/gitfaq.txt
> @@ -243,6 +243,16 @@ I want to change the remote of my repository. How do I do that?::
>  One can list the remotes of a repository using `git remote -v` command.
>  The default name of a remote is 'origin'.
>
> +[[shallow-cloning]]

Why is this marked as "shallow-cloning"?

> +The repository I am trying to clone is too big. Is there an alternative
> +way of cloning it in lesser space?::
> +       A good way to save up space when cloning a repository is

"save space" instead of "save up space"?

> +       by using `partial clones`. A partial clone will clone the
> +       full history of the repository but will skip out the entities
> +       specified by the `--filter` option one uses in `git clone`.
> +       Any entity which has not been cloned to save space can be cloned
> +       on-demand. See linkgit:partial-clone[1].
> +

I like this much better than suggesting shallow clones, though you
should mention that partial clones (currently?) presume that you have
an always-on network connection to the original repository because
subsequent commands may need to fetch additional objects in order to
complete.

Re: [PATCH v4 3/4] gitfaq: shallow cloning a repository

[Shourya Shukla]

On 29/04 09:00, Elijah Newren wrote:
> > diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
> > index 7d294306f9..6f32846e3d 100644
> > --- a/Documentation/gitfaq.txt
> > +++ b/Documentation/gitfaq.txt
> > @@ -243,6 +243,16 @@ I want to change the remote of my repository. How do I do that?::
> >  One can list the remotes of a repository using `git remote -v` command.
> >  The default name of a remote is 'origin'.
> >
> > +[[shallow-cloning]]
> 
> Why is this marked as "shallow-cloning"?

I forgot to change the heading, will fix it right away.

> > +The repository I am trying to clone is too big. Is there an alternative
> > +way of cloning it in lesser space?::
> > +       A good way to save up space when cloning a repository is
> 
> "save space" instead of "save up space"?

Sure.

> > +       by using `partial clones`. A partial clone will clone the
> > +       full history of the repository but will skip out the entities
> > +       specified by the `--filter` option one uses in `git clone`.
> > +       Any entity which has not been cloned to save space can be cloned
> > +       on-demand. See linkgit:partial-clone[1].
> > +
> 
> I like this much better than suggesting shallow clones, though you
> should mention that partial clones (currently?) presume that you have
> an always-on network connection to the original repository because
> subsequent commands may need to fetch additional objects in order to
> complete.

Alright, I will add that. Thank you for the review :)

Re: [PATCH v4 3/4] gitfaq: shallow cloning a repository

[Junio C Hamano]

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

> Add issue in 'Common issue' section which covers issues with cloning
> large repositories. Use partial cloning to selectively clone the
> repository.
>
> Signed-off-by: Shourya Shukla <shouryashukla.oo@gmail.com>
> ---
> I wanted to ask why is there no mention of partial cloning in
> the 'git-clone' documentation? Is it because it is an experimental
> feature?

If the folks that have been pushing the feature haven't bothered to
document it fully, by definition, it must be a work in progress that
is not ready for the prime time ;-)

Jokes aside, the --filter=<filter-spec> option is mentioned in the
documentation and it says "...is used for the partial clone filter",
without even defining what a "partial clone filter" really is.

The topic deserves its own subsection, between the "Git URLs" and
the "Examples" sections, in git-clone(1).

>  Documentation/gitfaq.txt | 10 ++++++++++
>  1 file changed, 10 insertions(+)
>
> diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
> index 7d294306f9..6f32846e3d 100644
> --- a/Documentation/gitfaq.txt
> +++ b/Documentation/gitfaq.txt
> @@ -243,6 +243,16 @@ I want to change the remote of my repository. How do I do that?::
>  One can list the remotes of a repository using `git remote -v` command.
>  The default name of a remote is 'origin'.
>  
> +[[shallow-cloning]]
> +The repository I am trying to clone is too big. Is there an alternative
> +way of cloning it in lesser space?::
> +	A good way to save up space when cloning a repository is
> +	by using `partial clones`. A partial clone will clone the
> +	full history of the repository but will skip out the entities
> +	specified by the `--filter` option one uses in `git clone`.
> +	Any entity which has not been cloned to save space can be cloned
> +	on-demand. See linkgit:partial-clone[1].

Where does this link go?

Re: [PATCH v4 3/4] gitfaq: shallow cloning a repository

[Shourya Shukla]

On 29/04 10:09, Junio C Hamano wrote:
> > ---
> > I wanted to ask why is there no mention of partial cloning in
> > the 'git-clone' documentation? Is it because it is an experimental
> > feature?
> 
> If the folks that have been pushing the feature haven't bothered to
> document it fully, by definition, it must be a work in progress that
> is not ready for the prime time ;-)
> 
> Jokes aside, the --filter=<filter-spec> option is mentioned in the
> documentation and it says "...is used for the partial clone filter",
> without even defining what a "partial clone filter" really is.
> 
> The topic deserves its own subsection, between the "Git URLs" and
> the "Examples" sections, in git-clone(1).

May I try to add it? If yes then are there any points to be kept in mind
while writing this part (for eg., length of the subsection, writing
style, what all is to be written etc.)?
> 
> >  Documentation/gitfaq.txt | 10 ++++++++++
> >  1 file changed, 10 insertions(+)
> >
> > diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
> > index 7d294306f9..6f32846e3d 100644
> > --- a/Documentation/gitfaq.txt
> > +++ b/Documentation/gitfaq.txt
> > @@ -243,6 +243,16 @@ I want to change the remote of my repository. How do I do that?::
> >  One can list the remotes of a repository using `git remote -v` command.
> >  The default name of a remote is 'origin'.
> >  
> > +[[shallow-cloning]]
> > +The repository I am trying to clone is too big. Is there an alternative
> > +way of cloning it in lesser space?::
> > +	A good way to save up space when cloning a repository is
> > +	by using `partial clones`. A partial clone will clone the
> > +	full history of the repository but will skip out the entities
> > +	specified by the `--filter` option one uses in `git clone`.
> > +	Any entity which has not been cloned to save space can be cloned
> > +	on-demand. See linkgit:partial-clone[1].
> 
> Where does this link go?

Actually I intended to link to this page:
https://git-scm.com/docs/partial-clone

Do we link such pages in a manner different from linking command
documentations? Also, lets say I want to link this section using
gitlink:
https://git-scm.com/docs/git-clone#_git_urls

Do we change the number in 'linkgit:git-clone[n]'? If yes, then how do
we decide that number?

Re: [PATCH v4 3/4] gitfaq: shallow cloning a repository

[Junio C Hamano]

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

> On 29/04 10:09, Junio C Hamano wrote:
>> > ---
>> > I wanted to ask why is there no mention of partial cloning in
>> > the 'git-clone' documentation? Is it because it is an experimental
>> > feature?
>> 
>> If the folks that have been pushing the feature haven't bothered to
>> document it fully, by definition, it must be a work in progress that
>> is not ready for the prime time ;-)
>> 
>> Jokes aside, the --filter=<filter-spec> option is mentioned in the
>> documentation and it says "...is used for the partial clone filter",
>> without even defining what a "partial clone filter" really is.
>> 
>> The topic deserves its own subsection, between the "Git URLs" and
>> the "Examples" sections, in git-clone(1).
>
> May I try to add it? If yes then are there any points to be kept in mind
> while writing this part (for eg., length of the subsection, writing
> style, what all is to be written etc.)?

I am much less qualified to answer these questions than others on
the CC: list.

Who added the mention to --filter and "used for the partial clone filter"
to the page anyway?  Did you run "git blame" to find out?

    ... goes and looks ...

It was added by 4a465443 (clone: document --filter options, 2020-03-22).

Derrick, perhaps you can help Shourya to find a good place to give
a birds-eye description for the partial-clone feature and figure out
what points about the feature are worth covering there?

Thanks.

Re: [PATCH v4 3/4] gitfaq: shallow cloning a repository

[Derrick Stolee]

On 5/4/2020 12:06 PM, Junio C Hamano wrote:
> Shourya Shukla <shouryashukla.oo@gmail.com> writes:
> 
>> On 29/04 10:09, Junio C Hamano wrote:
>>>> ---
>>>> I wanted to ask why is there no mention of partial cloning in
>>>> the 'git-clone' documentation? Is it because it is an experimental
>>>> feature?
>>>
>>> If the folks that have been pushing the feature haven't bothered to
>>> document it fully, by definition, it must be a work in progress that
>>> is not ready for the prime time ;-)
>>>
>>> Jokes aside, the --filter=<filter-spec> option is mentioned in the
>>> documentation and it says "...is used for the partial clone filter",
>>> without even defining what a "partial clone filter" really is.
>>>
>>> The topic deserves its own subsection, between the "Git URLs" and
>>> the "Examples" sections, in git-clone(1).
>>
>> May I try to add it? If yes then are there any points to be kept in mind
>> while writing this part (for eg., length of the subsection, writing
>> style, what all is to be written etc.)?
> 
> I am much less qualified to answer these questions than others on
> the CC: list.
> 
> Who added the mention to --filter and "used for the partial clone filter"
> to the page anyway?  Did you run "git blame" to find out?
> 
>     ... goes and looks ...
> 
> It was added by 4a465443 (clone: document --filter options, 2020-03-22).
> 
> Derrick, perhaps you can help Shourya to find a good place to give
> a birds-eye description for the partial-clone feature and figure out
> what points about the feature are worth covering there?

Yes, in the series that added those options I requested help in
documenting the partial clone. This was started in [1] but seems
to have gone stale. 

CC'ing Dyrone to see where they are with this.

Shourya: would you be willing to help the patch [1] get finished?
You could probably incorporate it into this series (adding your
sign-off). Let's see if Dyrone gets back to us.

Thanks,
-Stolee

[1] https://lore.kernel.org/git/c1a44a35095e7d681c312ecaa07c46e49f2fae67.1586791560.git.gitgitgadget@gmail.com/

Re: [PATCH v4 3/4] gitfaq: shallow cloning a repository

[dyrone teng]

Sorry, I was taking attention on other place and totally forgot that.

I will restart to look into the patch again today

Derrick Stolee <stolee@gmail.com> 于2020年5月5日周二 下午8:26写道：
>
> On 5/4/2020 12:06 PM, Junio C Hamano wrote:
> > Shourya Shukla <shouryashukla.oo@gmail.com> writes:
> >
> >> On 29/04 10:09, Junio C Hamano wrote:
> >>>> ---
> >>>> I wanted to ask why is there no mention of partial cloning in
> >>>> the 'git-clone' documentation? Is it because it is an experimental
> >>>> feature?
> >>>
> >>> If the folks that have been pushing the feature haven't bothered to
> >>> document it fully, by definition, it must be a work in progress that
> >>> is not ready for the prime time ;-)
> >>>
> >>> Jokes aside, the --filter=<filter-spec> option is mentioned in the
> >>> documentation and it says "...is used for the partial clone filter",
> >>> without even defining what a "partial clone filter" really is.
> >>>
> >>> The topic deserves its own subsection, between the "Git URLs" and
> >>> the "Examples" sections, in git-clone(1).
> >>
> >> May I try to add it? If yes then are there any points to be kept in mind
> >> while writing this part (for eg., length of the subsection, writing
> >> style, what all is to be written etc.)?
> >
> > I am much less qualified to answer these questions than others on
> > the CC: list.
> >
> > Who added the mention to --filter and "used for the partial clone filter"
> > to the page anyway?  Did you run "git blame" to find out?
> >
> >     ... goes and looks ...
> >
> > It was added by 4a465443 (clone: document --filter options, 2020-03-22).
> >
> > Derrick, perhaps you can help Shourya to find a good place to give
> > a birds-eye description for the partial-clone feature and figure out
> > what points about the feature are worth covering there?
>
> Yes, in the series that added those options I requested help in
> documenting the partial clone. This was started in [1] but seems
> to have gone stale.
>
> CC'ing Dyrone to see where they are with this.
>
> Shourya: would you be willing to help the patch [1] get finished?
> You could probably incorporate it into this series (adding your
> sign-off). Let's see if Dyrone gets back to us.
>
> Thanks,
> -Stolee
>
> [1] https://lore.kernel.org/git/c1a44a35095e7d681c312ecaa07c46e49f2fae67.1586791560.git.gitgitgadget@gmail.com/

[PATCH v4 4/4] gitfaq: fetching and pulling a repository

[Shourya Shukla]

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

Re: [PATCH v4 4/4] gitfaq: fetching and pulling a repository

[Elijah Newren]

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.

Re: [PATCH v4 4/4] gitfaq: fetching and pulling a repository

[Junio C Hamano]

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.

Re: [PATCH v4 4/4] gitfaq: fetching and pulling a repository

[Shourya Shukla]

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?

Re: [PATCH v4 4/4] gitfaq: fetching and pulling a repository

[Elijah Newren]

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

Re: [PATCH v4 4/4] gitfaq: fetching and pulling a repository

[Junio C Hamano]

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.

Re: [PATCH v4 1/4] gitfaq: files in .gitignore are tracked

[Elijah Newren]

On Wed, Apr 29, 2020 at 2:38 AM Shourya Shukla
<shouryashukla.oo@gmail.com> wrote:
>
> Add issue in 'Common Issues' section which addresses the problem of
> Git tracking files/paths mentioned in '.gitignore'.
>
> Signed-off-by: Shourya Shukla <shouryashukla.oo@gmail.com>
> ---
>  Documentation/gitfaq.txt | 9 +++++++++
>  1 file changed, 9 insertions(+)
>
> diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
> index 1cf83df118..b1e758ffd1 100644
> --- a/Documentation/gitfaq.txt
> +++ b/Documentation/gitfaq.txt
> @@ -223,6 +223,15 @@ a file checked into the repository which is a template or set of defaults which
>  can then be copied alongside and modified as appropriate.  This second, modified
>  file is usually ignored to prevent accidentally committing it.
>
> +[[files-in-.gitignore-are-tracked]]
> +I asked Git to ignore various files, yet they are still tracked::
> +       A `gitignore` file specifies intentionally untracked files
> +       that Git should ignore. Files already tracked by Git are
> +       not affected. See linkgit:gitignore[5] for details.
> +       To ignore and untrack the files appearing in the staging are
> +       it is advised to use `git rm --cached <file>`as well as make
> +       the file pattern is mentioned in the '.gitignore'.

Mostly looks good, but I can't help but nitpick several small items:
The first sentence alone seems to slightly undercut the answer, so
it'd be nice to make sure the first two sentences are just one.  Also,
it doesn't explain how people get into this state, which is probably
something users are curious about.  The "To ignore and untrack the
files" lists multiple end results, making it unclear which parts of
the end results the suggested steps are addressing.  There's also a
"staging are" typo (should be "staging area").

How about something like:

The purpose of gitignore files is to ensure that certain files not
tracked by Git remain untracked.  However, git allows people to
override the `gitignore` rules by using the --force option to `git
add`, and sometimes people started tracking a file unintentionally
before adding a pattern covering it to the gitignore rules.  If you
want to untrack a file, run `git rm --cached <file>` (and then
commit).  See linkgit:gitignore[5] for details.

Re: [PATCH v4 1/4] gitfaq: files in .gitignore are tracked

[Shourya Shukla]

On 29/04 09:16, Elijah Newren wrote: 
> Mostly looks good, but I can't help but nitpick several small items:
> The first sentence alone seems to slightly undercut the answer, so
> it'd be nice to make sure the first two sentences are just one.  Also,
> it doesn't explain how people get into this state, which is probably
> something users are curious about.  The "To ignore and untrack the
> files" lists multiple end results, making it unclear which parts of
> the end results the suggested steps are addressing.  There's also a
> "staging are" typo (should be "staging area").
> 
> How about something like:
> 
> The purpose of gitignore files is to ensure that certain files not
> tracked by Git remain untracked.  However, git allows people to
> override the `gitignore` rules by using the --force option to `git
> add`, and sometimes people started tracking a file unintentionally
> before adding a pattern covering it to the gitignore rules.  If you
> want to untrack a file, run `git rm --cached <file>` (and then
> commit).  See linkgit:gitignore[5] for details.

This seems better, will improve. :)

Re: [PATCH v4 1/4] gitfaq: files in .gitignore are tracked

[Junio C Hamano]

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

> Add issue in 'Common Issues' section which addresses the problem of
> Git tracking files/paths mentioned in '.gitignore'.
>
> Signed-off-by: Shourya Shukla <shouryashukla.oo@gmail.com>
> ---
>  Documentation/gitfaq.txt | 9 +++++++++
>  1 file changed, 9 insertions(+)
>
> diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
> index 1cf83df118..b1e758ffd1 100644
> --- a/Documentation/gitfaq.txt
> +++ b/Documentation/gitfaq.txt
> @@ -223,6 +223,15 @@ a file checked into the repository which is a template or set of defaults which
>  can then be copied alongside and modified as appropriate.  This second, modified
>  file is usually ignored to prevent accidentally committing it.
>  
> +[[files-in-.gitignore-are-tracked]]
> +I asked Git to ignore various files, yet they are still tracked::
> +	A `gitignore` file specifies intentionally untracked files
> +	that Git should ignore. Files already tracked by Git are
> +	not affected. See linkgit:gitignore[5] for details.
> +	To ignore and untrack the files appearing in the staging are
> +	it is advised to use `git rm --cached <file>`as well as make
> +	the file pattern is mentioned in the '.gitignore'.

After trimming down, it got a lot more readable.  The last sentence
is not quite, though, with riddled with typos.  Also the order of
untrack/ignore and steps to achieve these two things should match in
the description.

	To untrack and ignore files, use `git rm --cached <file>`
	and add a pattern to `.gitignore` that matches the <file>.

may be the minimum fix.

Thanks.