On 2020-04-13 at 14:09:18, Shourya Shukla wrote: > +[[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. > ++ > +Now that we have an idea of the key differences between merging and rebasing, we can look at the > +circumstances when we would want to perform them. Generally, merging is preferred when one desires > +to create a new feature, perform its integration testing with the original codebase, and finally > +integrate it if all tests are passed. One would choose to create a separate branch for this purpose > +and maybe dissolve it when the merge is done. > ++ > +One might want to perform a rebase when they intend to retain the changes made in a separate branch > +into their original branch. In that case, a rebase would place the former changes onto the commit tree > +of the latter. > ++ > +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., all in one package. I like the way you've clearly delineated the two typical use cases. As we know, some people have more other, different workflows, but I think you've given the right amount of detail here. Maybe we should recommend a link to git-rebase(1) to let folks read up on interactive rebase if they're interested in learning more. > +[[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'. Consequently, `git add` does not list these files as 'modified' even if any > + change was made in them and `git status` does not bother to track the changes in these files > + either. > + > + But, '.gitignore' will only ignore the files which were not a part of the repository when they > + were mentioned in the it. 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 amend this mistake, i.e., > + to untrack and completely ignore a tracked file, 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(presuming > + the file has been added in the 'gitignore'). This will hence make our file behave exactly like > + we described in the paragraph above. I think we want to put a space before these two parentheticals, and I believe it's customary to put a comma after "i.e." or "e.g.". There are some other cases below where I saw these two items as well. > +[[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>`. I suspect we may have some users who don't know what name they should use. Should we maybe suggest using "git remote -v" somewhere here to list the remotes and their existing URLs? As an alternative, we could mention that "origin" is the name of the default remote. Also, I think we want to capitalize "URL" when we write it in prose. > + 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. Many of us are familiar with "iff", but it is a bit confusing to folks without a mathematical background or people who aren't native English speakers, and so it might be better to avoid it in documentation targeted to newer users. Can we also maybe add a sentence to explain how one accesses the changes? For example, if one has done "git fetch origin", maybe we should say that the branch master on that remote can be viewed with "origin/master". > + 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, a 'checkout' serves three purposes, namely: > + > + 1. Go to another 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., referring to a named branch(say, master). > + Instead the aforementioned pointer is referring to the specified commit. I can now work upon the > + checked out commit and make any changes or just inspect the files at that state. > + > + 2. Go to a different version of a particular file; let's say I want to go to a particular version > + of a file in my working tree. I can again "checkout" to that particular version(i.e., going to a > + particular commit where certain changes were made). This can be done by entering the SHA1 of the > + commit in question. > + > + 3. 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. Let's phrase this so that the common case (that is, checking out a branch) is first (both here and below). That way, the user can say, "Yes, that's exactly what I want to do," and skip the rest. It's good to mention the other parts, but there are some users who are so new that they're not to the point of the other features, and we can help them by letting them skip over the things they don't yet understand. Also, it looks like there may be some trailing whitespace above (which I've trimmed in my message). > ++ > +To checkout to a commit, one can either pass the SHA1 of the commit to be checked out or a reference to it w.r.t. > +the HEAD. To checkout to a particular version of a file, one can use `git checkout <SHA1/reference> <file>`. > +To checkout to an already existing branch, one should use `git checkout <branch-name>`. To simultaneously create > +and checkout to a branch, one can use the `-b` option in the aforementioned command. > +One can observe how versatile the checkout command is, yet due to simplify things even further, two commands were > +introduced in version 2.23 of Git so as to break down the functionalities of `git checkout` and make it learning > +the command easier for a beginner. The commands being `git switch` and `git restore`. Let's prefer spelling out "with regard to" (or "with respect to") for those who aren't native speakers of English. "i.e." and "e.g." are extraordinarily common and are probably understandable, but my experience as a non-native speaker of Spanish and French is that abbreviations are tricky if you're not completely fluent, and "w.r.t." isn't that common in most prose. Maybe we also want to use a term other than "SHA1", such as "object ID" or "hash", seeing as work is ongoing to add a new hash function. > +`git restore` combines the first two features of the checkout as well as functionalities of `git reset` and `git revert` > +at one place so as to improve the functionality of the command. > ++ > +`git switch` perfoms the third functionality of the `git checkout` command, i.e., manipulating branches(creation). I wonder if we should prefer teaching "git switch" and "git restore" over the more complex features of "git checkout", and mention the variants of "git checkout" as a backup for those using older versions of Git. While I don't use them personally, the feedback I've received from others is that they are much easier to use and reason about than git checkout. Overall, let me say that I'm pretty happy with the way this is coming together and I appreciate you coming up with this series. I'm sorry I didn't have more time to look over this earlier before v2. -- brian m. carlson: Houston, Texas, US OpenPGP: https://keybase.io/bk2204
Attachment:
signature.asc
Description: PGP signature
