[PATCH v3 0/4] gitfaq: add issues in the 'Common Issues' section

[PATCH v3 0/4] gitfaq: add issues in the 'Common Issues' section

[Shourya Shukla]

This is the third version of addition of issues in the 'Common Issues' section.
In this version I have:
	1. Changed column wrapping from 90 col. to ~70 col.
	2. Removed the issues: 'rebasing-and-merging' & 'checking-out'
	3. Added issue: 'shallow-cloning'
	4. Separated the issues in individual commits.
	5. Corrected spelling and grammatical mistakes.

I decided to drop the issues mentioned in (2) because of the lack of clarity
in them. As Junio advised, it would be better to improve their respective
documentations rather than adding them in the FAQ.

I really appreciate Junio and Brian for reviewing my patch in such great detail :)

Regards,
Shourya Shukla

Shourya Shukla (4):
  gitfaq: files in .gitignore are tracked
  gitfaq: changing the remote of a repository
  gitfaq: shallow cloning a repository
  gitfaq: fetching and pulling a repository

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

-- 
2.20.1

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

diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
index 1cf83df118..96767e7c75 100644
--- a/Documentation/gitfaq.txt
+++ b/Documentation/gitfaq.txt
@@ -223,6 +223,27 @@ 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::
+	Git ignores files matching the patterns stated in the '.gitignore'.
+	Consequently, `git add` does not add the files/paths matching the
+	pattern in `.gitignore`, meaning they remain untracked; `git status`
+	does not list the aforementioned files/paths as untracked.
+
+	One thing to note is that the `.gitignore` mechanism applies only
+	to the files that are not already tracked. A file/path that is
+	already tracked will stay to be tracked even if you add a pattern
+	that happens to match it to `.gitignore` file.
+
+	This is probably the reason why Git shows some files/paths in the
+	staging area. These entities were being tracked before and later
+	were added in the `.gitignore`, due to which they show up in the
+	staging area.
+
+	To completely ignore and untrack files/paths falling in the above
+	category, it is advised to use `git rm --cached <file>` as well as
+	add these files/paths in the `.gitignore`.
+
 Hooks
 -----
 
-- 
2.20.1

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

diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
index 96767e7c75..13d37f96af 100644
--- a/Documentation/gitfaq.txt
+++ b/Documentation/gitfaq.txt
@@ -244,6 +244,37 @@ I asked Git to ignore various files, yet they are still tracked::
 	category, it is advised to use `git rm --cached <file>` as well as
 	add these files/paths 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:
+
+		1. One might want to update the URL of their remote; in that
+		   case, the command to use is, `git remote set-url <name> <newurl>`.
+
+		2. One might want to have two different remotes for fetching
+		   and pushing; this generally happens in case of triangular
+		   workflows: one fetches from one repository and pushes to
+		   another. In this case, it is advisable to have separate
+		   remotes for fetching and pushing. But, another way can be
+		   to change the push URL using the `--push` option in the
+		   `git set-url` command.
+
+		3. One might want to push changes to a network protocol
+		   different from the one they fetch from. For instance,
+		   one may be using an unauthenticated http:// URL for
+		   fetching from a repository and use an ssh:// URL when
+		   you push via the same remote. In such a case, one can
+		   change the 'push' URL of the same remote using the `--push`
+		   option in `git remote set-url`. Now, the same remote will
+		   have two different kinds of URLs (http and ssh) for fetching
+		   and pulling.
++
+One can list the remotes of a repository using `git remote -v` command.
+The default name of a remote is 'origin'.
+
 Hooks
 -----
 
-- 
2.20.1

[PATCH v3 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 cea293cf07..e93785f2f8 100644
--- a/Documentation/gitfaq.txt
+++ b/Documentation/gitfaq.txt
@@ -289,6 +289,26 @@ way of cloning it in lesser space?::
 	would mean fetching only the top level commits of the repository
 	See linkgit:git-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.20.1

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

diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
index 1cf83df118..96767e7c75 100644
--- a/Documentation/gitfaq.txt
+++ b/Documentation/gitfaq.txt
@@ -223,6 +223,27 @@ 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::
+	Git ignores files matching the patterns stated in the '.gitignore'.
+	Consequently, `git add` does not add the files/paths matching the
+	pattern in `.gitignore`, meaning they remain untracked; `git status`
+	does not list the aforementioned files/paths as untracked.
+
+	One thing to note is that the `.gitignore` mechanism applies only
+	to the files that are not already tracked. A file/path that is
+	already tracked will stay to be tracked even if you add a pattern
+	that happens to match it to `.gitignore` file.
+
+	This is probably the reason why Git shows some files/paths in the
+	staging area. These entities were being tracked before and later
+	were added in the `.gitignore`, due to which they show up in the
+	staging area.
+
+	To completely ignore and untrack files/paths falling in the above
+	category, it is advised to use `git rm --cached <file>` as well as
+	add these files/paths in the `.gitignore`.
+
 Hooks
 -----
 
-- 
2.20.1

Re: [PATCH v3 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'.

I do not think this much text is warranted in this file.

The first part of Documentation/gitignore.txt *ought* to cover this
material and it does say "specifies intentionally untracked files"
and "already tracked byt Git are not affected".  Read that paragarph
twice, and then jump to the NOTES section it refers two and also
read that twice.  Then let's work on polishing these places if there
is anything unclear.  I think what we have there is clear enough.

And then trim the text we see here down.  The way the question is
phrased may be good as-is (I trust that you researched to make sure
that is how the question is most frequently phrased).  The answer
should be just "see gitignore(5)", or perhaps repeat the first
paragraph of gitignore(5) and then refer to the page, i.e. no more
than

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

should be in the FAQ file.