[2/2] gitfaq: append the 'Common Issues' section
diff mbox series

Message ID 20200406181216.5340-3-shouryashukla.oo@gmail.com
State New
Headers show
Series
  • Add more issues in gitfaq
Related show

Commit Message

Shourya Shukla April 6, 2020, 6:12 p.m. UTC
Add more issues and their respective solutions in the 'Common Issues'
section of gitfaq.

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

Comments

Junio C Hamano April 6, 2020, 7:28 p.m. UTC | #1
Shourya Shukla <shouryashukla.oo@gmail.com> writes:

> +[[rebasing-and-merging]]
> +How do I know when to merge or rebase?::
> +	Rebasing and merging two entirely different concepts with different utiilites.

Can you wrap these lines at a more reasonable column, like 65-72?

> +	In Git terms, rebasing means to place changes made in one branch over another branch
> +	(called base, hence the term rebase). The commit history of the branch wanting to rebase
> +	get placed over the branch on the receiving end and it appears as if those changes took
> +	place in the receiving branch itself. Merging, as the name suggests, merges the latest
> +	commit of one branch onto the recent branch, making this combination appear as one separate
> +	commit.

There is nothing technically wrong per-se in the above, but is this
worth saying here, instead of polishing the tutorial or rebase/merge
manual pages?  Also, in the above, I do not see much that would help
readers to decide which one between merge and rebase to choose.

> +[[files-in-.gitignore-are-tracked]]
> +I asked Git to ignore various files, yet they show up as changes in my staging area::
> +	One uses `.gitignore` to ignore files from getting tracked in the working tree. This ignores
> +	the aforementioned files for the whole lifetime of the project unless they area removed from
> +	the `.gitignore`.

This should mention "git add" (and possibly "git status") somewhere.
You list patterns to match cruft you want to "IGNORE", (i.e. would
not want to track), so that "git add ." would ignore it, and "git
status" won't make noises about them not being tracked.

> But, `.gitignore` will only ignore the files which were not a part of the
> +	repository when they were mentioned in the `.gitignore`. Hence, addition of a file to `.gitignore`
> +	after it was added to the working tree will have no effect and Git will keep tracking them.
> +	To prevent this from happening, one has to use `git rm --cached <file>` to remove the file
> +	from the staging area(i.e. the cache) and not from the repository. 

That's not "prevent this from happening".  It is more like
recovering from an earlier mistake of adding what you did not want
to add.

But people ask ".gitignore does not ignore, my vendor.o file is
tracked, and I want changes to vendor.o to be ignored" in the
context of "once tracked, .gitignore would ont kick in", so the
above advice to "remove from the tracked set" would not even help
them.  Their expectation needs to be adjusted, and an entry in FAQ
you are trying to add is a good place to do so.

> +[[checking-out]]
> +What is checking out a commit/branch? How do I perform one?::
> +	In Git terminology, checking out means updating the current working tree with a another commit or
> +	even a separate tree(which would translate to a branch).

Unless you are going to mention "switch" and "restore", you should
stress the fact that "checkout" checks out two separate things for
two different purposes upfront, in the first sentence.

 - Checking out a branch (or a commit) is to set up the working tree
   files in preparation for working on the history of the branch
   (most often, to grow the history by adding more commits, but
   sometimes to edit the history by rebasing).

 - Checking out individual paths out of a tree-ish (most often, a
   commit) is to grab a verbatim copy of the path recorded in the
   tree-ish to update the files in the working tree, and is done to
   work on the history of the current branch.

People found the "checkout" command confusing, as the distinction
between the two weren't clearly taught to them.  More recent
versions of Git introduced "switch" and "restore" subcommands that
can be used only for the former and for the latter purpose,
respectively.

Thanks.

Patch
diff mbox series

diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
index 3ca16b1092..ccc14774ba 100644
--- a/Documentation/gitfaq.txt
+++ b/Documentation/gitfaq.txt
@@ -223,6 +223,78 @@  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.
 
+[[rebasing-and-merging]]
+How do I know when to merge or rebase?::
+	Rebasing and merging two entirely different concepts with different utiilites.
+	In Git terms, rebasing means to place changes made in one branch over another branch
+	(called base, hence the term rebase). The commit history of the branch wanting to rebase
+	get placed over the branch on the receiving end and it appears as if those changes took
+	place in the receiving branch itself. Merging, as the name suggests, merges the latest
+	commit of one branch onto the recent branch, making this combination appear as one separate
+	commit.
++
+As an additional tip, one can use interactive rebasing, `git rebase -i`, to perform rebasing
+using a text editor GUI (the value of $GIT_EDITOR). Interactive rebase is an excellent utility
+to perform various functions such as editing commit messages, dropping/squashing commits, editing
+commits, etc. in one package.
+
+[[files-in-.gitignore-are-tracked]]
+I asked Git to ignore various files, yet they show up as changes in my staging area::
+	One uses `.gitignore` to ignore files from getting tracked in the working tree. This ignores
+	the aforementioned files for the whole lifetime of the project unless they area removed from
+	the `.gitignore`. But, `.gitignore` will only ignore the files which were not a part of the
+	repository when they were mentioned in the `.gitignore`. Hence, addition of a file to `.gitignore`
+	after it was added to the working tree will have no effect and Git will keep tracking them.
+	To prevent this from happening, one has to use `git rm --cached <file>` to remove the file
+	from the staging area(i.e. the cache) and not from the repository. 
+
+[[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(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. In this case, it is advisable to create a
+		   separate remote just for fetching/pushing. But, another way can be to change the push
+		   url using the `--push` option in the `git set-url` command.
+
+[[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(iff 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.
+
+[[checking-out]]
+What is checking out a commit/branch? How do I perform one?::
+	In Git terminology, checking out means updating the current working tree with a another commit or
+	even a separate tree(which would translate to a branch). This means that if I were to:
+		1. Go to another commit, to lets say modify stuff in that commit; I would be "checking out"
+		   to that commit and enter a "detached HEAD" state, meaning, that the "pointer" called HEAD
+		   which tells me where I am right now in my working tree is not where it generally should be,
+		   i.e., the latest commit(or the tip of the branch). I can now work upon the checked out
+		   commit and make any changes or just inspect the files at that state.
+
+		2. Go to another branch or create another branch; I would be "checking out" to another tree
+		   in my local repository. One might expect to enter a detached HEAD here as well but in fact
+		   does not. This is because HEAD would point to the tip of the checked out branch, something
+		   which is not a characteristic of a detached HEAD.
++
+To checkout to a commit, one can either pass the SHA1 of the commit to be checked out or a reference to it wrt
+the HEAD. To checkout to another already existing branch, one should use `git checkout <branch-name>`.
+Also, one can create a new branch as well as checkout to it at the same time using `git checkout -b <new-branch-name>`.
+
 Hooks
 -----