{"thread":{"id":"53218","subject":"[PATCH v2 0/1] update gitfaq","startedAt":"2020-04-13T14:09:35Z","lastAt":"2020-04-21T18:00:09Z","messageCount":10,"participants":["Shourya Shukla","brian m. carlson","Junio C Hamano"],"isPatch":true,"patchVersion":2,"patchTotal":1},"messages":[{"id":"395334","messageId":"20200413140918.4778-1-shouryashukla.oo@gmail.com","threadId":"53218","inReplyTo":null,"subject":"[PATCH v2 0/1] update gitfaq","fromName":"Shourya Shukla","fromEmail":"shouryashukla.oo@gmail.com","sentAt":"2020-04-13T14:09:17Z","receivedAt":"2020-04-13T14:09:35Z","isPatch":true,"sender":{"key":"shouryashukla.oo@gmail.com","avatar":"https://avatars.githubusercontent.com/u/43680618?v=4"},"body":"Hello,\n\nThank you Junio and Brian for reviewing my patch :)\nhttps://lore.kernel.org/git/20200406181216.5340-1-shouryashukla.oo@gmail.com/\n\nThe changes in this version are:\n\t1. Dropped the gitfaq cleanup patch.\n\t2. Improved the 'rebasing and merging' section. Added information on when to rebase/merge.\n\t3. Improved the 'files-in-.gitignore-are-tracked' section. Added significance of `git add` & `git status`.\n\t4. Improved the 'checking-out' section. Added more description in use cases of `git checkout` as well as introduced\n\t `git switch` and `git restore`.\n\t5. Improvements in sentence formation and the terms used.\n\nRegards,\nShourya Shukla\n\nShourya Shukla (1):\n gitfaq: append the 'Common Issues' section\n\n Documentation/gitfaq.txt | 104 +++++++++++++++++++++++++++++++++++++++\n 1 file changed, 104 insertions(+)\n\n-- \n2.20.1\n\n"},{"id":"395335","messageId":"20200413140918.4778-2-shouryashukla.oo@gmail.com","threadId":"53218","inReplyTo":"20200413140918.4778-1-shouryashukla.oo@gmail.com","subject":"[PATCH v2 1/1] gitfaq: append the 'Common Issues' section","fromName":"Shourya Shukla","fromEmail":"shouryashukla.oo@gmail.com","sentAt":"2020-04-13T14:09:18Z","receivedAt":"2020-04-13T14:09:39Z","isPatch":true,"sender":{"key":"shouryashukla.oo@gmail.com","avatar":"https://avatars.githubusercontent.com/u/43680618?v=4"},"body":"Add more issues and their respective solutions in the 'Common Issues'\nsection of gitfaq.\n\nSigned-off-by: Shourya Shukla \n---\n Documentation/gitfaq.txt | 104 +++++++++++++++++++++++++++++++++++++++\n 1 file changed, 104 insertions(+)\n\ndiff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt\nindex 1cf83df118..fc261cbbf5 100644\n--- a/Documentation/gitfaq.txt\n+++ b/Documentation/gitfaq.txt\n@@ -223,6 +223,110 @@ a file checked into the repository which is a template or set of defaults which\n can then be copied alongside and modified as appropriate. This second, modified\n file is usually ignored to prevent accidentally committing it.\n \n+[[rebasing-and-merging]]\n+How do I know when to merge or rebase?::\n+\tRebasing and merging two entirely different concepts with different utiilites.\n+\tIn Git terms, rebasing means to place changes made in one branch over another branch\n+\t(called base, hence the term, rebase). The commit history of the branch wanting to rebase\n+\tget placed over the branch on the receiving end and it appears as if those changes took\n+\tplace in the receiving branch itself. Merging, as the name suggests, merges the latest\n+\tcommit of one branch onto the recent branch, making this combination appear as one separate\n+\tcommit.\n++\n+Now that we have an idea of the key differences between merging and rebasing, we can look at the\n+circumstances when we would want to perform them. Generally, merging is preferred when one desires\n+to create a new feature, perform its integration testing with the original codebase, and finally\n+integrate it if all tests are passed. One would choose to create a separate branch for this purpose\n+and maybe dissolve it when the merge is done.\n++\n+One might want to perform a rebase when they intend to retain the changes made in a separate branch\n+into their original branch. In that case, a rebase would place the former changes onto the commit tree\n+of the latter.\n++\n+As an additional tip, one can use interactive rebasing, `git rebase -i`, to perform rebasing\n+using a text editor GUI (the value of $GIT_EDITOR). Interactive rebase is an excellent utility\n+to perform various functions such as editing commit messages, dropping/squashing commits, editing\n+commits, etc., all in one package.\n+\n+[[files-in-.gitignore-are-tracked]]\n+I asked Git to ignore various files, yet they show up as changes in my staging area::\n+\tOne uses '.gitignore' to ignore files from getting tracked in the working tree. This ignores\n+\tthe aforementioned files for the whole lifetime of the project unless they area removed from\n+\tthe '.gitignore'. Consequently, `git add` does not list these files as 'modified' even if any\n+\tchange was made in them and `git status` does not bother to track the changes in these files\n+\teither.\n+\n+\tBut, '.gitignore' will only ignore the files which were not a part of the repository when they\n+\twere mentioned in the it. Hence, addition of a file to '.gitignore' after it was added to the\n+\tworking tree will have no effect and Git will keep tracking them. To amend this mistake, i.e.,\n+\tto untrack and completely ignore a tracked file, one has to use `git rm --cached ` to\n+\tremove the file from the staging area(i.e. the cache) and not from the repository(presuming\n+\tthe file has been added in the 'gitignore'). This will hence make our file behave exactly like\n+\twe described in the paragraph above.\n+\n+[[changing-remote-of-the-repository]]\n+I want to change the remote of my repository. How do I do that?::\n+\tA remote is an identifier for a location to which Git pushes your changes as well as fetches\n+\tany new changes(if any). There might be different circumstances in which one might need to change\n+\tthe remote:\n+\n+\t\t1. One might want to update the url of their remote; in that case, the command to use is,\n+\t\t `git remote set-url `.\n+\n+\t\t2. One might want to have two different remotes for fetching and pushing; this generally\n+\t\t happens in case of triangular workflows. In this case, it is advisable to create a\n+\t\t separate remote just for fetching/pushing. But, another way can be to change the push\n+\t\t url using the `--push` option in the `git set-url` command.\n+\n+[[fetching-and-pulling]]\n+How do I know if I want to do a fetch or a pull?::\n+\tA fetch brings in the latest changes made upstream(i.e. the remote repository we are working on).\n+\tThis allows us to inspect the changes made upstream and integrate all those changes(iff we want to)\n+\tor only cherry pick certain changes. Fetching does not have any immediate effects on the local\n+\trepository.\n+\n+\tA pull is a wrapper for a fetch and merge. This means that doing a `git pull` will not only fetch the\n+\tchanges made upstream but integrate them as well with our local repository. The merge may go smoothly\n+\tor have merge conflicts depending on the case. A pull does not allow you to review any changes made\n+\tupstream but rather merge those changes on their own.\n++\n+This is the reason why it is sometimes advised to fetch the changes first and then merge them accordingly\n+because not every change might be of utility to the user.\n+\n+[[checking-out]]\n+What is checking out a commit/branch? How do I perform one?::\n+\tIn Git terminology, a 'checkout' serves three purposes, namely:\n+\n+\t\t1. Go to another commit; I would be \"checking out\" to that commit and enter a \"detached HEAD\"\n+\t\t state, meaning, that the \"pointer\" called HEAD which tells me where I am right now in my\n+\t\t working tree is not where it generally should be, i.e., referring to a named branch(say, master).\n+\t\t Instead the aforementioned pointer is referring to the specified commit. I can now work upon the\n+\t\t checked out commit and make any changes or just inspect the files at that state.\n+\n+\t\t2. Go to a different version of a particular file; let's say I want to go to a particular version\n+\t\t of a file in my working tree. I can again \"checkout\" to that particular version(i.e., going to a\n+\t\t particular commit where certain changes were made). This can be done by entering the SHA1 of the\n+\t\t commit in question. \n+\n+\t\t3. Go to another branch or create another branch; I would be \"checking out\" to another tree\n+\t\t in my local repository. One might expect to enter a detached HEAD here as well but in fact\n+\t\t does not. This is because HEAD would point to the tip of the checked out branch, something\n+\t\t which is not a characteristic of a detached HEAD.\t\n++\n+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.\n+the HEAD. To checkout to a particular version of a file, one can use `git checkout `.\n+To checkout to an already existing branch, one should use `git checkout `. To simultaneously create\n+and checkout to a branch, one can use the `-b` option in the aforementioned command.\n++\n+One can observe how versatile the checkout command is, yet due to simplify things even further, two commands were\n+introduced in version 2.23 of Git so as to break down the functionalities of `git checkout` and make it learning\n+the command easier for a beginner. The commands being `git switch` and `git restore`.\n++\n+`git restore` combines the first two features of the checkout as well as functionalities of `git reset` and `git revert`\n+at one place so as to improve the functionality of the command.\n++\n+`git switch` perfoms the third functionality of the `git checkout` command, i.e., manipulating branches(creation).\n+\n Hooks\n -----\n \n-- \n2.20.1\n\n"},{"id":"395386","messageId":"20200414010601.GB2751707@camp.crustytoothpaste.net","threadId":"53218","inReplyTo":"20200413140918.4778-2-shouryashukla.oo@gmail.com","subject":"Re: [PATCH v2 1/1] gitfaq: append the 'Common Issues' section","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2020-04-14T01:06:01Z","receivedAt":"2020-04-14T01:06:41Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2020-04-13 at 14:09:18, Shourya Shukla wrote:\n> +[[rebasing-and-merging]]\n> +How do I know when to merge or rebase?::\n> +\tRebasing and merging two entirely different concepts with different utiilites.\n> +\tIn Git terms, rebasing means to place changes made in one branch over another branch\n> +\t(called base, hence the term, rebase). The commit history of the branch wanting to rebase\n> +\tget placed over the branch on the receiving end and it appears as if those changes took\n> +\tplace in the receiving branch itself. Merging, as the name suggests, merges the latest\n> +\tcommit of one branch onto the recent branch, making this combination appear as one separate\n> +\tcommit.\n> ++\n> +Now that we have an idea of the key differences between merging and rebasing, we can look at the\n> +circumstances when we would want to perform them. Generally, merging is preferred when one desires\n> +to create a new feature, perform its integration testing with the original codebase, and finally\n> +integrate it if all tests are passed. One would choose to create a separate branch for this purpose\n> +and maybe dissolve it when the merge is done.\n> ++\n> +One might want to perform a rebase when they intend to retain the changes made in a separate branch\n> +into their original branch. In that case, a rebase would place the former changes onto the commit tree\n> +of the latter.\n> ++\n> +As an additional tip, one can use interactive rebasing, `git rebase -i`, to perform rebasing\n> +using a text editor GUI (the value of $GIT_EDITOR). Interactive rebase is an excellent utility\n> +to perform various functions such as editing commit messages, dropping/squashing commits, editing\n> +commits, etc., all in one package.\n\nI like the way you've clearly delineated the two typical use cases. As\nwe know, some people have more other, different workflows, but I think\nyou've given the right amount of detail here.\n\nMaybe we should recommend a link to git-rebase(1) to let folks read up\non interactive rebase if they're interested in learning more.\n\n> +[[files-in-.gitignore-are-tracked]]\n> +I asked Git to ignore various files, yet they show up as changes in my staging area::\n> +\tOne uses '.gitignore' to ignore files from getting tracked in the working tree. This ignores\n> +\tthe aforementioned files for the whole lifetime of the project unless they area removed from\n> +\tthe '.gitignore'. Consequently, `git add` does not list these files as 'modified' even if any\n> +\tchange was made in them and `git status` does not bother to track the changes in these files\n> +\teither.\n> +\n> +\tBut, '.gitignore' will only ignore the files which were not a part of the repository when they\n> +\twere mentioned in the it. Hence, addition of a file to '.gitignore' after it was added to the\n> +\tworking tree will have no effect and Git will keep tracking them. To amend this mistake, i.e.,\n> +\tto untrack and completely ignore a tracked file, one has to use `git rm --cached ` to\n> +\tremove the file from the staging area(i.e. the cache) and not from the repository(presuming\n> +\tthe file has been added in the 'gitignore'). This will hence make our file behave exactly like\n> +\twe described in the paragraph above.\n\nI think we want to put a space before these two parentheticals, and I\nbelieve it's customary to put a comma after \"i.e.\" or \"e.g.\". There are\nsome other cases below where I saw these two items as well.\n\n> +[[changing-remote-of-the-repository]]\n> +I want to change the remote of my repository. How do I do that?::\n> +\tA remote is an identifier for a location to which Git pushes your changes as well as fetches\n> +\tany new changes(if any). There might be different circumstances in which one might need to change\n> +\tthe remote:\n> +\n> +\t\t1. One might want to update the url of their remote; in that case, the command to use is,\n> +\t\t `git remote set-url `.\n\nI suspect we may have some users who don't know what name they should\nuse. Should we maybe suggest using \"git remote -v\" somewhere here to\nlist the remotes and their existing URLs? As an alternative, we could\nmention that \"origin\" is the name of the default remote.\n\nAlso, I think we want to capitalize \"URL\" when we write it in prose.\n\n> +\t\t2. One might want to have two different remotes for fetching and pushing; this generally\n> +\t\t happens in case of triangular workflows. In this case, it is advisable to create a\n> +\t\t separate remote just for fetching/pushing. But, another way can be to change the push\n> +\t\t url using the `--push` option in the `git set-url` command.\n> +\n> +[[fetching-and-pulling]]\n> +How do I know if I want to do a fetch or a pull?::\n> +\tA fetch brings in the latest changes made upstream(i.e. the remote repository we are working on).\n> +\tThis allows us to inspect the changes made upstream and integrate all those changes(iff we want to)\n> +\tor only cherry pick certain changes. Fetching does not have any immediate effects on the local\n> +\trepository.\n\nMany of us are familiar with \"iff\", but it is a bit confusing to folks\nwithout a mathematical background or people who aren't native English\nspeakers, and so it might be better to avoid it in documentation\ntargeted to newer users.\n\nCan we also maybe add a sentence to explain how one accesses the\nchanges? For example, if one has done \"git fetch origin\", maybe we\nshould say that the branch master on that remote can be viewed with\n\"origin/master\".\n\n> +\tA pull is a wrapper for a fetch and merge. This means that doing a `git pull` will not only fetch the\n> +\tchanges made upstream but integrate them as well with our local repository. The merge may go smoothly\n> +\tor have merge conflicts depending on the case. A pull does not allow you to review any changes made\n> +\tupstream but rather merge those changes on their own.\n> ++\n> +This is the reason why it is sometimes advised to fetch the changes first and then merge them accordingly\n> +because not every change might be of utility to the user.\n> +\n> +[[checking-out]]\n> +What is checking out a commit/branch? How do I perform one?::\n> +\tIn Git terminology, a 'checkout' serves three purposes, namely:\n> +\n> +\t\t1. Go to another commit; I would be \"checking out\" to that commit and enter a \"detached HEAD\"\n> +\t\t state, meaning, that the \"pointer\" called HEAD which tells me where I am right now in my\n> +\t\t working tree is not where it generally should be, i.e., referring to a named branch(say, master).\n> +\t\t Instead the aforementioned pointer is referring to the specified commit. I can now work upon the\n> +\t\t checked out commit and make any changes or just inspect the files at that state.\n> +\n> +\t\t2. Go to a different version of a particular file; let's say I want to go to a particular version\n> +\t\t of a file in my working tree. I can again \"checkout\" to that particular version(i.e., going to a\n> +\t\t particular commit where certain changes were made). This can be done by entering the SHA1 of the\n> +\t\t commit in question.\n> +\n> +\t\t3. Go to another branch or create another branch; I would be \"checking out\" to another tree\n> +\t\t in my local repository. One might expect to enter a detached HEAD here as well but in fact\n> +\t\t does not. This is because HEAD would point to the tip of the checked out branch, something\n> +\t\t which is not a characteristic of a detached HEAD.\n\nLet's phrase this so that the common case (that is, checking out a\nbranch) is first (both here and below). That way, the user can say,\n\"Yes, that's exactly what I want to do,\" and skip the rest. It's good\nto mention the other parts, but there are some users who are so new that\nthey're not to the point of the other features, and we can help them by\nletting them skip over the things they don't yet understand.\n\nAlso, it looks like there may be some trailing whitespace above (which\nI've trimmed in my message).\n\n> ++\n> +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.\n> +the HEAD. To checkout to a particular version of a file, one can use `git checkout `.\n> +To checkout to an already existing branch, one should use `git checkout `. To simultaneously create\n> +and checkout to a branch, one can use the `-b` option in the aforementioned command.\n> +One can observe how versatile the checkout command is, yet due to simplify things even further, two commands were\n> +introduced in version 2.23 of Git so as to break down the functionalities of `git checkout` and make it learning\n> +the command easier for a beginner. The commands being `git switch` and `git restore`.\n\nLet's prefer spelling out \"with regard to\" (or \"with respect to\") for\nthose who aren't native speakers of English. \"i.e.\" and \"e.g.\" are\nextraordinarily common and are probably understandable, but my\nexperience as a non-native speaker of Spanish and French is that\nabbreviations are tricky if you're not completely fluent, and \"w.r.t.\"\nisn't that common in most prose.\n\nMaybe we also want to use a term other than \"SHA1\", such as \"object ID\"\nor \"hash\", seeing as work is ongoing to add a new hash function.\n\n> +`git restore` combines the first two features of the checkout as well as functionalities of `git reset` and `git revert`\n> +at one place so as to improve the functionality of the command.\n> ++\n> +`git switch` perfoms the third functionality of the `git checkout` command, i.e., manipulating branches(creation).\n\nI wonder if we should prefer teaching \"git switch\" and \"git restore\"\nover the more complex features of \"git checkout\", and mention the\nvariants of \"git checkout\" as a backup for those using older versions of\nGit. While I don't use them personally, the feedback I've received from\nothers is that they are much easier to use and reason about than git\ncheckout.\n\nOverall, let me say that I'm pretty happy with the way this is coming\ntogether and I appreciate you coming up with this series. I'm sorry I\ndidn't have more time to look over this earlier before v2.\n-- \nbrian m. carlson: Houston, Texas, US\nOpenPGP: https://keybase.io/bk2204\n"},{"id":"395397","messageId":"xmqqmu7ea5db.fsf@gitster.c.googlers.com","threadId":"53218","inReplyTo":"20200413140918.4778-2-shouryashukla.oo@gmail.com","subject":"Re: [PATCH v2 1/1] gitfaq: append the 'Common Issues' section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-04-14T07:33:36Z","receivedAt":"2020-04-14T07:33:43Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Shourya Shukla writes:\n\n> Add more issues and their respective solutions in the 'Common Issues'\n> section of gitfaq.\n\nIt probably would have been much easier to discuss if these sections\nwere separate patches.\n\nAlso, each physical line is way too long to view without line\nwrapping (even on my wider-than-usual 92 col terminal). Please wrap\nlines at a more reasonable column, like 65-72.\n\n> +[[rebasing-and-merging]]\n> +How do I know when to merge or rebase?::\n> +\tRebasing and merging two entirely different concepts with different utiilites.\n> +\tIn Git terms, rebasing means to place changes made in one branch over another branch\n> +\t(called base, hence the term, rebase). The commit history of the branch wanting to rebase\n> +\tget placed over the branch on the receiving end and it appears as if those changes took\n> +\tplace in the receiving branch itself.\n\n\"the branch wanting to rebase\"? Did you mean \"the branc being\nrebased\"? Except for that the above looks quite reasonable.\n\n> +\tMerging, as the name suggests, merges the latest\n> +\tcommit of one branch onto the recent branch, making this combination appear as one separate\n> +\tcommit.\n\nThis description is a bit iffy. There is nothing special about \"the\nlatest commit\" among the commits on the branch being merged---if you\nhad a two-commit side branch and you merged that branch to another\nbranch, the changes made by _both_ commits would appear in the\nresult; I don't find much value in saying \"the latest commit of one\nbranch\" (besides, merging an early part of a branch alone, while\nleaving more later parts of the branch still not merged, is a valid\nthing to do).\n\n Merging binds two (or more) lines of histories into one history,\n reflecting what these branches wanted to do to the files since\n they forked from their common ancestor and recording the result\n as one new \"merge\" commit that is a direct descendant of the\n tips of these branches.\n\nperhaps.\n\n[jc: it is impossible to comment on the overlong lines, so I'd\nremove the '+'(added) sign and reflow the paragraphs]\n\n> Now that we have an idea of the key differences between merging\n> and rebasing, we can look at the circumstances when we would want\n> to perform them.\n\nOK.\n\n> Generally, merging is preferred when one desires\n> to create a new feature, perform its integration testing with the\n> original codebase, and finally integrate it if all tests are\n> passed.\n\nThis is an unsubstantiated claim (opinion) and I do not know if I\nagree with it.\n\nI do not think we want to have such a sentence as if it were our\nofficial recommendation in our documentation set---it is OK to write\nsuch things on your blog, but not here.\n\n> One would choose to create a separate branch for this purpose and\n> maybe dissolve it when the merge is done.\n\nIt is unclear what you mean by \"dissolve\" here. Do you mean \"build\na new feature on a topic branch, use the branch to polish the feature\nuntil it is perfect, and merge it to the trunk, at which point, the\ntopic branch is no longer needed so it can be discarded\"?\n\n> One might want to perform a rebase when they intend to retain the\n> changes made in a separate branch into their original branch. \n\nThis reads as if you are describing: \"I want to keep the original,\nbut I want to use the same changes elsewhere\" but I do not think it\nis a good match for \"rebase\" in the first place. It sounds more\nlike you are talking about cherry-picking.\n\nAnd \"merge\" is also perfectly fine way to do so, as long as the\noriginal development was done based on the right commit. If you\noriginally based your fix on a commit that is too new in the\nhistory, even though the problem you wanted to fix appeared much\nearlier in the history, you obviously cannot fix the problem for an\nolder maintenance track by merging, and at that point, you may\neither\n\n (1) cherry-pick (i.e. duplicate) the fixes to older maintenance\n track, while keeping the fixes based on a newer codebase; or\n\n (2) rebase the fixes, that were originally done on a newer\n codebase, to the oldest maintenance track that still matters,\n and then discard the original fixes and instead merge the\n result of rebasing to the newer codebase.\n\nIf you can afford to do (2), it is _always_ preferrable to do so,\nbut often you cannot and you end up doing (1).\n\nNotice that the preferred workflow has *both* rebasing and merging\nas crucial elements. It's not like \"when to do rebase, and when to\nmerge\" as you set out this section to be. It is often more like\n\"you rebase, in preparation to merge\".\n\n> In that case, a rebase would place the former changes onto the\n> commit tree of the latter.\n\n> As an additional tip, one can use interactive rebasing, `git\n> rebase -i`, to perform rebasing using a text editor GUI (the value\n> of $GIT_EDITOR). Interactive rebase is an excellent utility to\n> perform various functions such as editing commit messages,\n> dropping/squashing commits, editing commits, etc., all in one\n> package.\n\nI think what the description is lacking *most* is *why* and without\nthat it would not be as useful as it could be to the readers. Why\ndoes one want to rebase commits on a branch? When the reader knows\nthe answer to that question clearly, various things \"rebase\" lets\nits users do would make sense.\n\nIn the context of \"I now have my first iteration of a topic (be it a\nfeature or a fix)\", one would perform rebase because of different\nreasons (and they are not exclusive):\n\n - Your first attempt may have been built on a wrong commit, so you\n want to restart your topic branch at a different \"base\".\n\n . You may have written a helper function in your code yourself,\n because you started your topic branch at the latest release\n tag, but later you may have noticed that the same helper\n function is already available for your use in the current\n development version. By restarting your topic branch at a\n later commit, you do not have to reinvent the helper function\n yourself, hence you may want to rebase your topic at the tip of\n the current development version.\n\n . You may have developed a fix on top of the latest release tag,\n but then realized that the bug you fixed was already there in\n the previous release. You obviously cannot merge your fix\n directly to the previous release, because doing so would also\n pull down all the changes in the latest release. By restarting\n your topic branch with your fix at the previous release point,\n you can apply the fix (and no other changes that the latest\n release has) to the earlier codebase. And if your newer\n codebase is a superset of your older codebase, you can fix the\n same bug in the newer codebase by simply merging the fix to the\n newer codebase (and your original topic branch based on the\n latest release tag is no longer needed, so you can discard it).\n\n - Your commits may have unnecessary or wrong code, or log message,\n or both. They may be in a wrong order. You would rebuild your\n history, either on the same base or a different one, and tweak\n each commit as you do so.\n\n And \"rebase -i\" was invented exactly for that purpose.\n\nI won't comment on the other sections in this message (I may do so\nin separate ones).\n\nThanks.\n"},{"id":"395614","messageId":"xmqqa73bz1x9.fsf@gitster.c.googlers.com","threadId":"53218","inReplyTo":"20200413140918.4778-2-shouryashukla.oo@gmail.com","subject":"Re: [PATCH v2 1/1] gitfaq: append the 'Common Issues' section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-04-16T19:05:38Z","receivedAt":"2020-04-16T19:05:47Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Shourya Shukla writes:\n\n> +[[files-in-.gitignore-are-tracked]]\n> +I asked Git to ignore various files, yet they show up as changes in my staging area::\n\n(again, I'll wrap overly long lines, as they were unreviewable otherwise)\n\n> +\tOne uses '.gitignore' to ignore files from getting tracked\n> +\tin the working tree. This ignores the aforementioned files\n> +\tfor the whole lifetime of the project unless they area\n> +\tremoved from the '.gitignore'.\n\nAt least \"they area\" -> \"they are\" is needed, but it is unclear\nwhere these two sentences one to go. \n\n\"to ignore files from getting tracked in the working tree\" is why\nyou may want to use the '.gitignore' file. That is OK. But the\nconnection to the next sentence, especially the subject \"This\nignores\", is hard to grok. I am guessing that you want to tell the\nusers something like\n\n\tPaths that match patterns listed in the `.gitignore` are\n\tnot meant to be tracked.\n\n\tThe act of adding a pattern in `.gitignore` that matches a\n\tset of paths that are not tracked is a declaration that you\n\tdo not intend to track these paths and a request by you to\n\tGit to help you achieve that goal.\n\nbut you are trying to state it in a more approachable manner. But I\nsense that you ended up being unclear.\n\n> +\tConsequently, `git add` does\n> +\tnot list these files as 'modified' even if any change was\n> +\tmade in them and `git status` does not bother to track the\n> +\tchanges in these files either.\n\nThis part is very much in line with the \"you are declaring and\nrequesting\". The user does not want to track these paths, and these\ncommands are helping the user to achieve that wish.\n\nHowever, \"`git add` does not list ...\" is questionable. by\ndefinition, Git does not care about contents of any untracked paths,\nso there is no way for us to say `modified` about them.\n\nThe primary utility of `git add` is to add a path, which used to be\nuntracked, to the set of the paths that are tracked. So perhaps\n\n\tTo help you keep the paths untracked, `git add` does not add\n\tthe paths that are not tracked and ignored without the\n\t`--force` option, and `git status` does not list them as\n\tuntracked (i.e. possible candidate that you might want to\n\tadd but forgot).\n\n> +\tBut, '.gitignore' will only ignore the files which were not\n> +\ta part of the repository when they were mentioned in the\n> +\tit.\n> + Hence, addition of a file to '.gitignore' after it was\n> +\tadded to the working tree will have no effect and Git will\n> +\tkeep tracking them.\n\nI am not sure wat you mean by the first sentence (even after\nremoving 'the' from \"in the it.\"). It does not matter if you wrote\nthe pattern '*.o' in the .gitignore file one year ago, or 7 seconds\nago. As long as hello.o in the working tree is not tracked, it is\nignored. Perhaps\n\n\tThe `.gitignore` mechanism applies only to the files that\n\tare not already tracked. A path that is already tracked\n\twill stay to be tracked even if you add a pattern that\n\thappens to match it to .gitignore file.\n\n> + To amend this mistake, i.e., to untrack\n> +\tand completely ignore a tracked file,\n\nI'd omit \"To amend this mistake, i.e.,\" from the above, if I were\nwriting this. Also, I see no value in saying \"completely\" here.\nIt is not like there are ways to half-ignore or fully-ignore ;-). \n\n> + one has to use `git rm\n> +\t--cached ` to remove the file from the staging\n> +\tarea(i.e. the cache) and not from the repository(presuming\n> +\tthe file has been added in the 'gitignore').\n\n\tTo untrack a tracked file, without removing it from the\n\tworking tree, \"git rm --cached \" can be used. To keep\n\tthe file ignored after doing so, make sure that `.gitignore`\n\tknows that the file is to be ignored (e.g. by adding \n\tto `.gitignore`, but you may already have a pattern that\n\tmatch there).\n\nHaving commented on this section, I am not sure why we need so much\ndescription here, instead of clarifying the existing documentation\nof the mechanism in the Documentation/gitignore.txt file.\n\nI think it is better to limit the FAQ list to two kinds of entries:\n\n * A topic that spans multiple mechanisms and features that is not\n easy to explain in a single documentation page may have to be\n described in place.\n\n * Other topics that already have authoritative description with\n adequate clarity in other pages should just have a summary\n paragraph that is less than 5 sentences, and a pointer to the\n authoritative page.\n\nThe `.gitignore` topic should fall into the latter category. It is\na separate issue if Documentation/gitignore.txt has rooms for\nimprovement and if so, I think it is more productive to propose a\npatch to it there, not adding too much description on the topic\nhere.\n\nThanks.\n\n\n"},{"id":"395615","messageId":"xmqq5zdzz0ih.fsf@gitster.c.googlers.com","threadId":"53218","inReplyTo":"20200413140918.4778-2-shouryashukla.oo@gmail.com","subject":"Re: [PATCH v2 1/1] gitfaq: append the 'Common Issues' section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-04-16T19:36:06Z","receivedAt":"2020-04-16T19:36:17Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Shourya Shukla writes:\n\n> +[[checking-out]]\n\n> +What is checking out a commit/branch? How do I perform one?::\n\n> +\tIn Git terminology, a 'checkout' serves three purposes, namely:\n\nWell, whoever is asking the question knows what s/he wants to do is\nto check out a commit/branch and not \"grab a version of files from\ndifferent tree\", so this is answering a question that is not asked.\n\nTeaching the distinction of two kinds of checkout [*] may be\nimportant, but then we should do so by answering a different\nquestion ;-)\n\n\tSide note. There are not three but two variants. There is\n\tno conceptual difference between checking out a branch and\n\tmoving to detached HEAD. They are both to prepare extending\n\tthe history that led to the commit (either the commit that\n\twas checked out, or the commit at the tip of the branch that\n\twas checked out); what is done to the resulting history is\n\tthe only difference (if you work on detached HEAD, you can\n\tdecide which branch to update with after you are finished\n\tworking, if you stay on a branch, you are committed to\n\tupdate that branch at the time of checking it out).\n\n> +\t\t1. Go to another commit; I would be \"checking out\"\n> +\t\tto that commit and enter a \"detached HEAD\" state,\n\n\"Check out\" is a direct verb, i.e. \"check out the commit\", not\n\"check out to the commit\". The same thing can be said to other uses\nin your document about checking out a path out of a tree-ish.\n\n> +\t\tmeaning, that the \"pointer\" called HEAD which tells\n> +\t\tme where I am right now in my working tree is not\n> +\t\twhere it generally should be, i.e., referring to a\n> +\t\tnamed branch(say, master). Instead the\n> +\t\taforementioned pointer is referring to the specified\n> +\t\tcommit. I can now work upon the checked out commit\n> +\t\tand make any changes or just inspect the files at\n> +\t\tthat state.\n> +\n> +\t\t2. Go to a different version of a particular file;\n\nWho is \"going\" and where? Isn't it easier to understand if you\nexplained that \"checking out a path out of a tree-ish\" is to grab a\ncopy of the blob (which is at the path in the tree-ish) and update\nthe working tree with it? \"Replace a file in the working tree with\nthe same file in a different commit\", perhaps?\n\n> +\t\tlet's say I want to go to a particular version of a\n\n\"go to\" -> \"have\" would make this understandable, at least to me.\n\n> +\t\tfile in my working tree. I can again \"checkout\" to\n> +\t\tthat particular version(i.e., going to a particular\n> +\t\tcommit where certain changes were made). This can be\n> +\t\tdone by entering the SHA1 of the commit in question.\n> +\n> +\t\t3. Go to another branch or create another branch; I\n> +\t\twould be \"checking out\" to another tree in my local\n> +\t\trepository. One might expect to enter a detached\n> +\t\tHEAD here as well but in fact does not.\n\nIt is unclear why one would expect such a behaviour. Is this really\na frequently asked question?\n\n> + This is\n> +\t\tbecause HEAD would point to the tip of the checked\n> +\t\tout branch, something which is not a characteristic\n> +\t\tof a detached HEAD.\n\n> ++\n> +To checkout to a commit, one can either pass the SHA1 of the\n> +commit to be checked out or a reference to it w.r.t. the HEAD.\n\nI do not know what you mean by \"or a reference to it w.r.t the\nHEAD\" here..\n\n> +To checkout to a particular version of a file, one can use `git\n> +checkout `. \n\nYou are getting confused here. This part belogs to #2 above,\ni.e. grabbing a path out of a tree-ish as a way to help growing the\ncurrent line of the history (either branch or the detached HEAD) you\nare working on. Not an appropriate sentence to have in the section\nfor #3, which is about switching the line of history you are going\nto grow.\n\n> + To checkout to an already\n> +existing branch, one should use `git checkout `. To\n> +simultaneously create and checkout to a branch, one can use the\n> +`-b` option in the aforementioned command.\n\nYes. But drop \"to\" from \"check out to\". You \"check out a branch\",\nnot \"check out to a branch\".\n\n> +One can observe how versatile the checkout command is, yet due to\n> +simplify things even further, two commands were introduced in\n> +version 2.23 of Git so as to break down the functionalities of\n> +`git checkout` and make it learning the command easier for a\n> +beginner.\n\nDrop \"even further\". A common complaint was that it was too\nversatile and introducing two separate commands for its two (again,\nnot three) uses was done to make it simpler and easier to learn and\nuse.\n\n> +The commands being `git switch` and `git restore`.\n> ++\n> +`git restore` combines the first two features of the checkout as\n> +well as functionalities of `git reset` and `git revert` at one\n> +place so as to improve the functionality of the command.\n\nAre you sure? I thought you artificially split \"switch\" into #1\n(switch to a detached HEAD) and #3 (switch to a branch) and\ndescribed \"check out paths out of tree-ish to the working tree\" as\n#2, which is what \"git restore\" is.\n\n> +`git switch` perfoms the third functionality of the `git checkout`\n> +command, i.e., manipulating branches(creation).\n\nDitto. Detach, orphan, creation, and plain branch switching all\nfall into \"switch\"'s purview.\n\nThe distinction to keep in mind is if you are checking out a line of\nhistory to work on, or if you are sticking to the current line of\nhistory and manipulating working tree files by grabbing contents of\npaths out of a different tree-ish.\n\nAgain, I am not sure why we need to have separate description about\ntwo primary modes of \"git checkout\" here, instead of making sure we\nhave serviceable explanation in \"git checkout\" manual page and point\nit from here, if \"what are two modes of checkout?\" is a frequently\nasked question. For those who started their Git experience with\n\"switch\" and \"restore\" without touching \"checkout\", the distinction\nmay not even have to be explained.\n\nThanks.\n"},{"id":"395799","messageId":"xmqqsggxpseq.fsf@gitster.c.googlers.com","threadId":"53218","inReplyTo":"20200413140918.4778-2-shouryashukla.oo@gmail.com","subject":"Re: [PATCH v2 1/1] gitfaq: append the 'Common Issues' section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-04-21T00:57:17Z","receivedAt":"2020-04-21T00:57:24Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Shourya Shukla writes:\n\n>+ [[changing-remote-of-the-repository]]\n>+ I want to change the remote of my repository. How do I do that?::\n\n>+ \tA remote is an identifier for a location to which Git pushes\n>+ \tyour changes as well as fetches any new changes(if\n>+ \tany).\n\nYou push changes to a repository.\nYou fetch changes from a repository.\n\nHence, \"a location, which you push changes to, as well as fetch new\nchanges from, if any.\" But a lot more people fetch from repositories\nthan push to repositories, so \"a location, which you fetch changes from,\nas well as push your changes to.\" may be easier to follow by audiences.\n\nIn any case there is one crucial and precious thing in what you\nwrote here. A remote is a name for *A* location, even if you have\ntwo URLs (i.e. one used for fetching from, and another used for\npushing to). They are to name logically the same place, only the\nway you reach may be different. For example, you may have an\nunauthenticated https:// URL for fetching, while the URL you use to\nthe repository may be ssh:// URL. But the important point is that\nthese URLs are about the same repository---if you push over ssh://\nURL your changes, you would be able to see the changes over https://\nURL that you use for fetching.\n\n>+ There might be different circumstances in which one\n>+ \tmight need to change the remote:\n\nSure.\n\n>+ \t\t1. One might want to update the url of their remote;\n>+ \t\tin that case, the command to use is, `git remote\n>+ \t\tset-url `.\n\nYes, this truly is \"changing\" the old one by replacing its old URL\nwith a new URL.\n\n>+ \t\t2. One might want to have two different remotes for\n>+ \t\tfetching and pushing; this generally happens in case\n>+ \t\tof triangular workflows. In this case, it is\n>+ \t\tadvisable to create a separate remote just for\n>+ \t\tfetching/pushing.\n\nYes, by definition, triangular is about fetching from somebody else\nand publishing to your own place for others to fetch, so you'd need\ntwo remotes, as you are not talking with a single repository.\n\nBut I find your phrasing quite confusing.\n\n\"advisable to have two remotes, one for fetching and the other for\npushing\" would probably be a lot more correct.\n\nAnd I can understand why you did not write so, and instead ended up\nwith your version. In order to reach the goal of having two (one\nfor push and one for fetch), you would \"create a separate remote\" as\nyou are likely to already have one for one direction (in other\nwords, you didn't want to say \"advisable to create two remotes\").\n\nYou wrote \"create a separate remote just for fetching/pushing\" and\nmade the direction of the new one vague, because you do not know if\nthat existing one is for fetching or pushing,\n\nBut I suspect that all of the above would not be as clear to those\nwho need their questions answered as to somebody like me who knows\nwhat you want to say already. And you do not want to explain things\nin a way that only is understood by experts. How about rephrasing\nthe above more like so?\n\n\t2. One may want to fetch from one repository and push to\n\tanther repository---this is often called a \"triangular\"\n\tworkflow. As you'd probably have one remote that you use\n\tfor fetching already created when you cloned the project,\n\tyou would want to create a separate remote to record the URL\n\tyou push to.\n\n>+ But, another way can be to change\n>+ \t\tthe push url using the `--push` option in the `git\n>+ \t\tset-url` command.\n\nDo not recommend this when you describe a triangular workflow; it is\nconfusing to readers. Keeping separate fetch and push URLs for a\nsingle remote is not triangular. \n\nDescribe it separately as a different use case, e.g.\n\n\t3. You may want to push to a repository over a network\n\tprotocol different from the one you use to fetch from the\n\trepository. Perhaps you want unauthenticated https:// URL\n\tfor fetching from, and use ssh:// URL when you push to, the\n\tsame remote. In such a case, ...\n\nOther than the above nits I picked, overall it is a good idea to\nraise this question in the FAQ, I would think.\n\nThanks.\n"},{"id":"395813","messageId":"20200421065853.GA11800@konoha","threadId":"53218","inReplyTo":"xmqqa73bz1x9.fsf@gitster.c.googlers.com","subject":"Re: [PATCH v2 1/1] gitfaq: append the 'Common Issues' section","fromName":"Shourya Shukla","fromEmail":"shouryashukla.oo@gmail.com","sentAt":"2020-04-21T06:58:53Z","receivedAt":"2020-04-21T06:59:02Z","isPatch":true,"sender":{"key":"shouryashukla.oo@gmail.com","avatar":"https://avatars.githubusercontent.com/u/43680618?v=4"},"body":"On 16/04 12:05, Junio C Hamano wrote:\n> Shourya Shukla writes:\n\n> \"to ignore files from getting tracked in the working tree\" is why\n> you may want to use the '.gitignore' file. That is OK. But the\n> connection to the next sentence, especially the subject \"This\n> ignores\", is hard to grok. I am guessing that you want to tell the\n> users something like\n> \n> \tPaths that match patterns listed in the `.gitignore` are\n> \tnot meant to be tracked.\n> \n> \tThe act of adding a pattern in `.gitignore` that matches a\n> \tset of paths that are not tracked is a declaration that you\n> \tdo not intend to track these paths and a request by you to\n> \tGit to help you achieve that goal.\n> \n> but you are trying to state it in a more approachable manner. But I\n> sense that you ended up being unclear.\n\nI apologise for this. I am understanding the concepts but I fail to put\nthem in words in English. I will try my best to not degrade the quality\nof important documentation such as this one.\n \n> This part is very much in line with the \"you are declaring and\n> requesting\". The user does not want to track these paths\n> Having commented on this section, I am not sure why we need so much\n> description here, instead of clarifying the existing documentation\n> of the mechanism in the Documentation/gitignore.txt file.\n> \n> I think it is better to limit the FAQ list to two kinds of entries:\n> \n> * A topic that spans multiple mechanisms and features that is not\n> easy to explain in a single documentation page may have to be\n> described in place.\n> \n> * Other topics that already have authoritative description with\n> adequate clarity in other pages should just have a summary\n> paragraph that is less than 5 sentences, and a pointer to the\n> authoritative page.\n> \n> The `.gitignore` topic should fall into the latter category. It is\n> a separate issue if Documentation/gitignore.txt has rooms for\n> improvement and if so, I think it is more productive to propose a\n> patch to it there, not adding too much description on the topic\n> here.\n\nI have seen this problem occur a lot so I decided to put it in the FAQ.\nI will try to shorten it and make it more 'to the point'.\n\nRegards,\nShourya Shukla\n"},{"id":"395815","messageId":"20200421083820.GB11800@konoha","threadId":"53218","inReplyTo":"xmqqsggxpseq.fsf@gitster.c.googlers.com","subject":"Re: [PATCH v2 1/1] gitfaq: append the 'Common Issues' section","fromName":"Shourya Shukla","fromEmail":"shouryashukla.oo@gmail.com","sentAt":"2020-04-21T08:38:20Z","receivedAt":"2020-04-21T08:38:29Z","isPatch":true,"sender":{"key":"shouryashukla.oo@gmail.com","avatar":"https://avatars.githubusercontent.com/u/43680618?v=4"},"body":"On 20/04 05:57, Junio C Hamano wrote:\n> Shourya Shukla writes:\n\n> >+ \t\t2. One might want to have two different remotes for\n> >+ \t\tfetching and pushing; this generally happens in case\n> >+ \t\tof triangular workflows. In this case, it is\n> >+ \t\tadvisable to create a separate remote just for\n> >+ \t\tfetching/pushing.\n> \n> Yes, by definition, triangular is about fetching from somebody else\n> and publishing to your own place for others to fetch, so you'd need\n> two remotes, as you are not talking with a single repository.\n> \n> But I find your phrasing quite confusing.\n\nI understand. My words turn out to be very ambiguous sometimes. I meant\ncreating a separate remote for fetch and separate one for push.\nApologies for the confusion.\n\n> \"advisable to have two remotes, one for fetching and the other for\n> pushing\" would probably be a lot more correct.\n> \n> And I can understand why you did not write so, and instead ended up\n> with your version. In order to reach the goal of having two (one\n> for push and one for fetch), you would \"create a separate remote\" as\n> you are likely to already have one for one direction (in other\n> words, you didn't want to say \"advisable to create two remotes\").\n> \n> You wrote \"create a separate remote just for fetching/pushing\" and\n> made the direction of the new one vague, because you do not know if\n> that existing one is for fetching or pushing,\n> \n> But I suspect that all of the above would not be as clear to those\n> who need their questions answered as to somebody like me who knows\n> what you want to say already. And you do not want to explain things\n> in a way that only is understood by experts. How about rephrasing\n> the above more like so?\n> \n> \t2. One may want to fetch from one repository and push to\n> \tanther repository---this is often called a \"triangular\"\n> \tworkflow. As you'd probably have one remote that you use\n> \tfor fetching already created when you cloned the project,\n> \tyou would want to create a separate remote to record the URL\n> \tyou push to.\n\nYep. I will add this. This reads out much better.\n\n> >+ But, another way can be to change\n> >+ \t\tthe push url using the `--push` option in the `git\n> >+ \t\tset-url` command.\n> \n> Do not recommend this when you describe a triangular workflow; it is\n> confusing to readers. Keeping separate fetch and push URLs for a\n> single remote is not triangular. \n\nI thought it would be OK to describe a maybe *unorthodox* way to do\nthis. I will remove it in the next version.\n\n> Describe it separately as a different use case, e.g.\n> \n> \t3. You may want to push to a repository over a network\n> \tprotocol different from the one you use to fetch from the\n> \trepository. Perhaps you want unauthenticated https:// URL\n> \tfor fetching from, and use ssh:// URL when you push to, the\n> \tsame remote. In such a case, ...\n\nThat sounds quite better. I will incorporate this.\nThank you so much for such a detailed review! :)\n\nRegards,\nShourya Shukla\n"},{"id":"395839","messageId":"xmqqo8rkoh27.fsf@gitster.c.googlers.com","threadId":"53218","inReplyTo":"20200421083820.GB11800@konoha","subject":"Re: [PATCH v2 1/1] gitfaq: append the 'Common Issues' section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-04-21T18:00:00Z","receivedAt":"2020-04-21T18:00:09Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Shourya Shukla writes:\n\n> I thought it would be OK to describe a maybe *unorthodox* way to do\n> this. I will remove it in the next version.\n\nThe thing is that it is not just unorthodox but it is wrong and\nbroken.\n\nImagine that your 'origin' fetches from upstream that is controlled\nby me (e.g. at https://github.com/git/git/) and pushes to your\npublishing repository controled by you. After you fetch from me\nafter my 'master' branch advances, of course, remote/origin/master\nwould be updated in your repository. When you work on your own\nchanges on your 'master' (perhaps you do \"pull --rebase origin\") and\npush the result to your publishing repository, which you also call\n'origin' because you configured the remotes in your \"unorthodox\"\nway, the remote-tracking branch remotes/origin/master would also be\nupdated from your 'master' (i.e. we pretend that we fetched the\nremote-tracking branches from the same remote immediately after we\npushed out). But if you actually fetch from 'origin', I wouldn't\nhave your changes on my 'master' yet, and you won't be seeing your\ncommits in your remotes/origin/master. \n\nI.e. the \"unorthodox\" way breaks your remote-tracking branch, and\nnot recommendable for any usecase.\n\nHaving said all that, because this is a single-topic FAQ entry that\ncovers only the \"remote\", we should clarify the existing description\nin Documentation/git-remote.txt and also possibly config variables\nthe subsystem uses so that anything readers would learn by\nunderstanding these three bullet points we just discussed are\ncovered there. And then have a small paragraph that has only the\nquestion and \"see that section on that manual page\" reference, and\nno duplicated explanation, in the FAQ file.\n\n"}]}