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

[PATCH v7 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 | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
index 1cf83df118..11d9bac859 100644
--- a/Documentation/gitfaq.txt
+++ b/Documentation/gitfaq.txt
@@ -223,6 +223,16 @@ 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 ensures that certain file(s) which are not
+	tracked by Git remain untracked.  However, sometimes particular
+	file(s) may have been tracked before adding them into the
+	`.gitignore`, hence they still remain tracked.  To untrack and
+	ignore files/patterns, use `git rm --cached <file/pattern>`
+	and add a pattern to `.gitignore` that matches the <file>.
+	See linkgit:gitignore[5] for details.
+
 Hooks
 -----
 
-- 
2.26.2

[PATCH v7 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.

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 11d9bac859..875cfa0acd 100644
--- a/Documentation/gitfaq.txt
+++ b/Documentation/gitfaq.txt
@@ -233,6 +233,17 @@ I asked Git to ignore various files, yet they are still tracked::
 	and add a pattern to `.gitignore` that matches the <file>.
 	See linkgit:gitignore[5] for details.
 
+[[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

[PATCH v7 3/4] gitfaq: partial 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>
---
Fixed a whitespace error pointed out by Elijah.

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

diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
index 875cfa0acd..5a6c8fb07e 100644
--- a/Documentation/gitfaq.txt
+++ b/Documentation/gitfaq.txt
@@ -244,6 +244,17 @@ 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'.
 
+[[partial-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 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 (hence this
+	presumes that the user has an always-on network connection to the
+	original repository).  See linkgit:partial-clone[1].
+
 Hooks
 -----
 
-- 
2.26.2

[PATCH v7 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'.

Helped-by: Elijah Newren <newren@gmail.com>
Signed-off-by: Shourya Shukla <shouryashukla.oo@gmail.com>
---
Fixed a whitespace error pointed out by Elijah.

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

diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
index 5a6c8fb07e..208e5e5b82 100644
--- a/Documentation/gitfaq.txt
+++ b/Documentation/gitfaq.txt
@@ -255,6 +255,14 @@ 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 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.  See linkgit:git-pull[1].
+
 Hooks
 -----
 
-- 
2.26.2

Re: [PATCH v7 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>
> ---

I'll queue only 1/4 and 4/4 for now, as these two among four haven't
changed in the last few rounds.  The remaining two are *not* rejected;
just are not yet in a shape ready to be queued.

Thanks.

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

[Son Luong Ngoc]

Hey folks,

> 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 | 10 ++++++++++
>  1 file changed, 10 insertions(+)
>
> diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
> index 1cf83df118..11d9bac859 100644
> --- a/Documentation/gitfaq.txt
> +++ b/Documentation/gitfaq.txt
> @@ -223,6 +223,16 @@ 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]]

This does not work for older xmlto(centos6) for whatever reason.
```
# make doc
...
# xmlto -m manpage-normal.xsl  -m manpage-bold-literal.xsl -m
manpage-base-url.xsl man gitfaq.xml
xmlto: /<git-dir>/Documentation/gitfaq.xml does not validate (status 3)
xmlto: Fix document syntax or use --skip-validation option
/<git-dir>/Documentation/gitfaq.xml:3: element refentry: validity
error : Element refentry content does not follow the DTD, expecting
(beginpage? , indexterm* , refentryinfo? , refmeta? , (remark | link |
olink | ulink)* , refnamediv+ , refsynopsisdiv? , (refsect1+ |
refsection+)), got (refmeta refnamediv refsynopsisdiv refsect1
refsect1 refsect1 refsect1 variablelist refsect1 refsect1 )
```

Build went fine on Centos7 and Centos8 though.

I ran a quick sed to temporarily fix the problem
```
sed -i 's/files-in-\.gitignore/files-in-gitignore/g' Documentation/gitfaq.txt
```

But I suggest to just remove the period from this heading.

> +I asked Git to ignore various files, yet they are still tracked::
> + A `gitignore` file ensures that certain file(s) which are not
> + tracked by Git remain untracked.  However, sometimes particular
> + file(s) may have been tracked before adding them into the
> + `.gitignore`, hence they still remain tracked.  To untrack and
> + ignore files/patterns, use `git rm --cached <file/pattern>`
> + and add a pattern to `.gitignore` that matches the <file>.
> + See linkgit:gitignore[5] for details.
> +
>  Hooks
>  -----
>
> --
> 2.26.2

Cheers,
Son Luong.

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

[Todd Zullinger]

Hi,

Son Luong Ngoc wrote:
> Hey folks,
> 
>> 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 | 10 ++++++++++
>>  1 file changed, 10 insertions(+)
>>
>> diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
>> index 1cf83df118..11d9bac859 100644
>> --- a/Documentation/gitfaq.txt
>> +++ b/Documentation/gitfaq.txt
>> @@ -223,6 +223,16 @@ 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]]
> 
> This does not work for older xmlto(centos6) for whatever reason.
> ```
> # make doc
> ...
> # xmlto -m manpage-normal.xsl  -m manpage-bold-literal.xsl -m
> manpage-base-url.xsl man gitfaq.xml
> xmlto: /<git-dir>/Documentation/gitfaq.xml does not validate (status 3)
> xmlto: Fix document syntax or use --skip-validation option
> /<git-dir>/Documentation/gitfaq.xml:3: element refentry: validity
> error : Element refentry content does not follow the DTD, expecting
> (beginpage? , indexterm* , refentryinfo? , refmeta? , (remark | link |
> olink | ulink)* , refnamediv+ , refsynopsisdiv? , (refsect1+ |
> refsection+)), got (refmeta refnamediv refsynopsisdiv refsect1
> refsect1 refsect1 refsect1 variablelist refsect1 refsect1 )
> ```

I ran into this as well.  I _think_ this is an asciidoc
issue (but it could be further up the doc tools chain).  On
CentOS 6, the asciidoc version is 8.4.5.  From earlier in
the make output:

    make[1]: Leaving directory `/builddir/build/BUILD/git-2.27.0.rc0'
    rm -f gitfaq.html+ gitfaq.html && \
	    asciidoc  -f asciidoc.conf -amanversion=2.27.0.rc0 -amanmanual='Git Manual' -amansource='Git' -b xhtml11 -d manpage -o gitfaq.html+ gitfaq.txt && \
	    mv gitfaq.html+ gitfaq.html
    WARNING: gitfaq.txt: line 245: missing [[files-in-.gitignore-are-tracked]] section

Dropping the "." from the anchor name works around the
failure, which seems like a reasonable thing to do.  With
the age of asciidoc and CentOS 6 approaching end-of-life
this November, we wouldn't want to spend too much effort to
work around issues there.  But this seems like an easy way
to allow the documentation to continue to build on such old
platforms.

There do appear to be other issues with the asciidoc's
parsing of the anchors, as some of the others are either not
included in the xml and html or are not quite in the place
they should be.  I didn't see an obvious reason for that,
but I didn't spend all that long looking over gitfaq.txt
because I imagine there are plenty of minor issues with
asciidoc-8.4.5.

I thought this change in asciidoc might have fixed the
issue:

    https://github.com/asciidoc/asciidoc/commit/4ceeb32

But I didn't have any luck after applying that to
asciidoc-8.4.5.

Anyway, here's the quick work-around in patch form.

-- >8 --
Subject: [PATCH] gitfaq: avoid validation error with older asciidoc

When building with asciidoc-8.4.5 (as found on CentOS/Red Hat 6), the
period in the "[[files-in-.gitignore-are-tracked]]" anchor is not
properly parsed as a section:

  WARNING: gitfaq.txt: line 245: missing [[files-in-.gitignore-are-tracked]] section

The resulting XML file fails to validate with xmlto:

    xmlto: /git/Documentation/gitfaq.xml does not validate (status 3)
    xmlto: Fix document syntax or use --skip-validation option
     /git/Documentation/gitfaq.xml:3: element refentry: validity error :
     Element refentry content does not follow the DTD, expecting
     (beginpage? , indexterm* , refentryinfo? , refmeta? , (remark | link
     | olink | ulink)* , refnamediv+ , refsynopsisdiv? , (refsect1+ |
     refsection+)), got (refmeta refnamediv refsynopsisdiv refsect1
     refsect1 refsect1 refsect1 variablelist refsect1 refsect1 )
    Document /git/Documentation/gitfaq.xml does not validate

Let's avoid breaking users of platforms which ship an old version of
asciidoc, since the cost to do so is quite low.

Reported-by: Son Luong Ngoc <sluongng@gmail.com>
Signed-off-by: Todd Zullinger <tmz@pobox.com>
---
 Documentation/gitfaq.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
index 370d62dae4..9cd7a592ac 100644
--- a/Documentation/gitfaq.txt
+++ b/Documentation/gitfaq.txt
@@ -223,7 +223,7 @@ 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]]
+[[files-in-gitignore-are-tracked]]
 I asked Git to ignore various files, yet they are still tracked::
 	A `gitignore` file ensures that certain file(s) which are not
 	tracked by Git remain untracked.  However, sometimes particular
-- 
2.26.1

-- >8 --

-- 
Todd