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

[PATCH v5 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>
---
Thank you Junio and Elijah for the review! :)
I have tried to make the solutions to the issues as concise and crisp
as possible, linking the Documentation wherever necessary. Also, I have
converted 1SP -> 2 SP after full stops(.).

 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 v5 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 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 v5 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 fixed the heading of this section and improved it overall though,
as pointed out by Junio, there is a bit confusion as to what URL I
am trying to point to:
https://git-scm.com/docs/partial-clone
This is the URL I want to point to.

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

diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
index 875cfa0acd..5dfbb32089 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 v5 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 | 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.
+
 Hooks
 -----
 
-- 
2.26.2

Re: [PATCH v5 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>
> ---
> Thank you Junio and Elijah for the review! :)
> I have tried to make the solutions to the issues as concise and crisp
> as possible, linking the Documentation wherever necessary. Also, I have
> converted 1SP -> 2 SP after full stops(.).

Indeed I find it concise and very much to the point.  Looks quite
well written.

Thanks, will queue (and please ping me if I forget ;-))

>
>  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
>  -----

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

[Elijah Newren]

On Sun, May 3, 2020 at 10:42 PM 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 | 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).

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

[Elijah Newren]

On Sun, May 3, 2020 at 10:42 PM Shourya Shukla
<shouryashukla.oo@gmail.com> wrote:
> Subject: [PATCH v5 3/4] gitfaq: shallow cloning a repository

Shouldn't the subject be updated as well, since we're talking about
partial clones rather than shallow clones?

> 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 fixed the heading of this section and improved it overall though,
> as pointed out by Junio, there is a bit confusion as to what URL I
> am trying to point to:
> https://git-scm.com/docs/partial-clone
> This is the URL I want to point to.
>
>  Documentation/gitfaq.txt | 11 +++++++++++
>  1 file changed, 11 insertions(+)
>
> diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
> index 875cfa0acd..5dfbb32089 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
>