{"thread":{"id":"53273","subject":"[PATCH v3 0/4] gitfaq: add issues in the 'Common Issues' section","startedAt":"2020-04-21T13:12:34Z","lastAt":"2020-04-27T17:30:58Z","messageCount":15,"participants":["Shourya Shukla","Junio C Hamano","Randall S. Becker","Elijah Newren","Derrick Stolee","Jonathan Nieder"],"isPatch":true,"patchVersion":3,"patchTotal":4},"messages":[{"id":"395827","messageId":"20200421131223.29337-1-shouryashukla.oo@gmail.com","threadId":"53273","inReplyTo":null,"subject":"[PATCH v3 0/4] gitfaq: add issues in the 'Common Issues' section","fromName":"Shourya Shukla","fromEmail":"shouryashukla.oo@gmail.com","sentAt":"2020-04-21T13:12:19Z","receivedAt":"2020-04-21T13:12:34Z","isPatch":true,"sender":{"key":"shouryashukla.oo@gmail.com","avatar":"https://avatars.githubusercontent.com/u/43680618?v=4"},"body":"This is the third version of addition of issues in the 'Common Issues' section.\nIn this version I have:\n\t1. Changed column wrapping from 90 col. to ~70 col.\n\t2. Removed the issues: 'rebasing-and-merging' & 'checking-out'\n\t3. Added issue: 'shallow-cloning'\n\t4. Separated the issues in individual commits.\n\t5. Corrected spelling and grammatical mistakes.\n\nI decided to drop the issues mentioned in (2) because of the lack of clarity\nin them. As Junio advised, it would be better to improve their respective\ndocumentations rather than adding them in the FAQ.\n\nI really appreciate Junio and Brian for reviewing my patch in such great detail :)\n\nRegards,\nShourya Shukla\n\nShourya Shukla (4):\n gitfaq: files in .gitignore are tracked\n gitfaq: changing the remote of a repository\n gitfaq: shallow cloning a repository\n gitfaq: fetching and pulling a repository\n\n Documentation/gitfaq.txt | 86 ++++++++++++++++++++++++++++++++++++++++\n 1 file changed, 86 insertions(+)\n\n-- \n2.20.1\n\n"},{"id":"395828","messageId":"20200421131223.29337-2-shouryashukla.oo@gmail.com","threadId":"53273","inReplyTo":"20200421131223.29337-1-shouryashukla.oo@gmail.com","subject":"[PATCH v3 1/4] gitfaq: files in .gitignore are tracked","fromName":"Shourya Shukla","fromEmail":"shouryashukla.oo@gmail.com","sentAt":"2020-04-21T13:12:20Z","receivedAt":"2020-04-21T13:12:37Z","isPatch":true,"sender":{"key":"shouryashukla.oo@gmail.com","avatar":"https://avatars.githubusercontent.com/u/43680618?v=4"},"body":"Add issue in 'Common Issues' section which addresses the problem of\nGit tracking files/paths mentioned in '.gitignore'.\n\nSigned-off-by: Shourya Shukla \n---\n Documentation/gitfaq.txt | 21 +++++++++++++++++++++\n 1 file changed, 21 insertions(+)\n\ndiff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt\nindex 1cf83df118..96767e7c75 100644\n--- a/Documentation/gitfaq.txt\n+++ b/Documentation/gitfaq.txt\n@@ -223,6 +223,27 @@ 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+[[files-in-.gitignore-are-tracked]]\n+I asked Git to ignore various files, yet they are still tracked::\n+\tGit ignores files matching the patterns stated in the '.gitignore'.\n+\tConsequently, `git add` does not add the files/paths matching the\n+\tpattern in `.gitignore`, meaning they remain untracked; `git status`\n+\tdoes not list the aforementioned files/paths as untracked.\n+\n+\tOne thing to note is that the `.gitignore` mechanism applies only\n+\tto the files that are not already tracked. A file/path that is\n+\talready tracked will stay to be tracked even if you add a pattern\n+\tthat happens to match it to `.gitignore` file.\n+\n+\tThis is probably the reason why Git shows some files/paths in the\n+\tstaging area. These entities were being tracked before and later\n+\twere added in the `.gitignore`, due to which they show up in the\n+\tstaging area.\n+\n+\tTo completely ignore and untrack files/paths falling in the above\n+\tcategory, it is advised to use `git rm --cached ` as well as\n+\tadd these files/paths in the `.gitignore`.\n+\n Hooks\n -----\n \n-- \n2.20.1\n\n"},{"id":"395829","messageId":"20200421131223.29337-3-shouryashukla.oo@gmail.com","threadId":"53273","inReplyTo":"20200421131223.29337-1-shouryashukla.oo@gmail.com","subject":"[PATCH v3 2/4] gitfaq: changing the remote of a repository","fromName":"Shourya Shukla","fromEmail":"shouryashukla.oo@gmail.com","sentAt":"2020-04-21T13:12:21Z","receivedAt":"2020-04-21T13:12:39Z","isPatch":true,"sender":{"key":"shouryashukla.oo@gmail.com","avatar":"https://avatars.githubusercontent.com/u/43680618?v=4"},"body":"Add issue in 'Common Issues' section which addresses the problem of\nchanging the remote of a repository, covering various cases in which\none might want to change the remote and the ways to do the same.\n\nSigned-off-by: Shourya Shukla \n---\n Documentation/gitfaq.txt | 31 +++++++++++++++++++++++++++++++\n 1 file changed, 31 insertions(+)\n\ndiff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt\nindex 96767e7c75..13d37f96af 100644\n--- a/Documentation/gitfaq.txt\n+++ b/Documentation/gitfaq.txt\n@@ -244,6 +244,37 @@ I asked Git to ignore various files, yet they are still tracked::\n \tcategory, it is advised to use `git rm --cached ` as well as\n \tadd these files/paths in the `.gitignore`.\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\n+\tchanges as well as fetches any new changes from (if any). There\n+\tmight 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\n+\t\t case, the command to use is, `git remote set-url `.\n+\n+\t\t2. One might want to have two different remotes for fetching\n+\t\t and pushing; this generally happens in case of triangular\n+\t\t workflows: one fetches from one repository and pushes to\n+\t\t another. In this case, it is advisable to have separate\n+\t\t remotes for fetching and pushing. But, another way can be\n+\t\t to change the push URL using the `--push` option in the\n+\t\t `git set-url` command.\n+\n+\t\t3. One might want to push changes to a network protocol\n+\t\t different from the one they fetch from. For instance,\n+\t\t one may be using an unauthenticated http:// URL for\n+\t\t fetching from a repository and use an ssh:// URL when\n+\t\t you push via the same remote. In such a case, one can\n+\t\t change the 'push' URL of the same remote using the `--push`\n+\t\t option in `git remote set-url`. Now, the same remote will\n+\t\t have two different kinds of URLs (http and ssh) for fetching\n+\t\t and pulling.\n++\n+One can list the remotes of a repository using `git remote -v` command.\n+The default name of a remote is 'origin'.\n+\n Hooks\n -----\n \n-- \n2.20.1\n\n"},{"id":"395830","messageId":"20200421131223.29337-4-shouryashukla.oo@gmail.com","threadId":"53273","inReplyTo":"20200421131223.29337-1-shouryashukla.oo@gmail.com","subject":"[PATCH v3 3/4] gitfaq: shallow cloning a repository","fromName":"Shourya Shukla","fromEmail":"shouryashukla.oo@gmail.com","sentAt":"2020-04-21T13:12:22Z","receivedAt":"2020-04-21T13:12:43Z","isPatch":true,"sender":{"key":"shouryashukla.oo@gmail.com","avatar":"https://avatars.githubusercontent.com/u/43680618?v=4"},"body":"Add issue in 'Common issue' section which covers issues with cloning\nlarge repositories. Use shallow cloning to clone the repository in\na smaller size.\n\nSigned-off-by: Shourya Shukla \n---\n Documentation/gitfaq.txt | 14 ++++++++++++++\n 1 file changed, 14 insertions(+)\n\ndiff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt\nindex 13d37f96af..cea293cf07 100644\n--- a/Documentation/gitfaq.txt\n+++ b/Documentation/gitfaq.txt\n@@ -275,6 +275,20 @@ I want to change the remote of my repository. How do I do that?::\n One can list the remotes of a repository using `git remote -v` command.\n The default name of a remote is 'origin'.\n \n+[[shallow-cloning]]\n+The repository I am trying to clone is too big. Is there an alternative\n+way of cloning it in lesser space?::\n+\tOne can clone a repository having a truncated history, meaning the\n+\thistory\twill span upto a specified number of commits instead of\n+\tthe whole history of the repository. This is called 'Shallow Cloning'.\n+\tThis helps to decrease the space taken up by the repository.\n+\tShallow cloning can be done by using the `--depth` option\n+\twhile cloning. Therefore, the command would look like:\n+\t`git clone --depth `.\n+\tHere, 'n' is the depth of the clone. For e.g., a depth of 1\n+\twould mean fetching only the top level commits of the repository\n+\tSee linkgit:git-clone[1].\n+\n Hooks\n -----\n \n-- \n2.20.1\n\n"},{"id":"395831","messageId":"20200421131223.29337-5-shouryashukla.oo@gmail.com","threadId":"53273","inReplyTo":"20200421131223.29337-1-shouryashukla.oo@gmail.com","subject":"[PATCH v3 4/4] gitfaq: fetching and pulling a repository","fromName":"Shourya Shukla","fromEmail":"shouryashukla.oo@gmail.com","sentAt":"2020-04-21T13:12:23Z","receivedAt":"2020-04-21T13:12:48Z","isPatch":true,"sender":{"key":"shouryashukla.oo@gmail.com","avatar":"https://avatars.githubusercontent.com/u/43680618?v=4"},"body":"Add an issue in 'Common Issues' section which addresses the confusion\nbetween performing a 'fetch' and a 'pull'.\n\nSigned-off-by: Shourya Shukla \n---\n Documentation/gitfaq.txt | 20 ++++++++++++++++++++\n 1 file changed, 20 insertions(+)\n\ndiff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt\nindex cea293cf07..e93785f2f8 100644\n--- a/Documentation/gitfaq.txt\n+++ b/Documentation/gitfaq.txt\n@@ -289,6 +289,26 @@ way of cloning it in lesser space?::\n \twould mean fetching only the top level commits of the repository\n \tSee linkgit:git-clone[1].\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\n+\tremote repository we are working on). This allows us to inspect\n+\tthe changes made upstream and integrate all those changes (if\n+\tand only if we want to) or only cherry pick certain changes.\n+\tFetching 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\n+\ta `git pull` will not only fetch the changes made upstream but\n+\tintegrate them as well with our local repository. The merge may\n+\tgo smoothly or have merge conflicts depending on the case. A pull\n+\tdoes not allow you to review any changes made upstream but rather\n+\tmerge those changes on their own.\n++\n+This is the reason why it is sometimes advised to fetch the changes\n+first and then merge them accordingly because not every change might\n+be of utility to the user.\n+\n Hooks\n -----\n \n-- \n2.20.1\n\n"},{"id":"395849","messageId":"xmqq7dy8oc5w.fsf@gitster.c.googlers.com","threadId":"53273","inReplyTo":"20200421131223.29337-2-shouryashukla.oo@gmail.com","subject":"Re: [PATCH v3 1/4] gitfaq: files in .gitignore are tracked","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-04-21T19:45:47Z","receivedAt":"2020-04-21T19:45:55Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Shourya Shukla writes:\n\n> Add issue in 'Common Issues' section which addresses the problem of\n> Git tracking files/paths mentioned in '.gitignore'.\n\nI do not think this much text is warranted in this file.\n\nThe first part of Documentation/gitignore.txt *ought* to cover this\nmaterial and it does say \"specifies intentionally untracked files\"\nand \"already tracked byt Git are not affected\". Read that paragarph\ntwice, and then jump to the NOTES section it refers two and also\nread that twice. Then let's work on polishing these places if there\nis anything unclear. I think what we have there is clear enough.\n\nAnd then trim the text we see here down. The way the question is\nphrased may be good as-is (I trust that you researched to make sure\nthat is how the question is most frequently phrased). The answer\nshould be just \"see gitignore(5)\", or perhaps repeat the first\nparagraph of gitignore(5) and then refer to the page, i.e. no more\nthan\n\n [[files-in-.gitignore-are-tracked]]\n I asked Git to ignore various files, yet they are still tracked::\n A `gitignore` file specifies intentionally untracked files\n that Git should ignore. Files already tracked by Git are\n not affected. See linkgit:gitignore[5] for details.\n\nshould be in the FAQ file.\n"},{"id":"395850","messageId":"xmqq368wobqu.fsf@gitster.c.googlers.com","threadId":"53273","inReplyTo":"20200421131223.29337-3-shouryashukla.oo@gmail.com","subject":"Re: [PATCH v3 2/4] gitfaq: changing the remote of a repository","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-04-21T19:54:49Z","receivedAt":"2020-04-21T19:54:58Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Shourya Shukla writes:\n\n> Add issue in 'Common Issues' section which addresses the problem of\n> changing the remote of a repository, covering various cases in which\n> one might want to change the remote and the ways to do the same.\n>\n> Signed-off-by: Shourya Shukla \n> ---\n> Documentation/gitfaq.txt | 31 +++++++++++++++++++++++++++++++\n> 1 file changed, 31 insertions(+)\n\nAgain, I think this belongs to Documentation/git-remote.txt; unlike\nthe \".gitignore\" one, however, the existing description is heavily\nconcentrated on \"what happens when X is set to Y?\" and does not\nanswer \"why would I want to set X to Y in the first place?\" very\nmuch. And the text below you have is a good thing to teach anybody\nwho learns \"git-remote\". \n\nSo how about clarifying the existing page, perhaps its DISCUSSION\nsection (which currently talks only about \"how to add a remote, and\nconfigure\" without discussing \"why would I want to add a remote, set\na URL and/or a pushURL to it\") with what you have, and trim the\ndescription here in the FAQ file to the minimum and refer to the\npage instead?\n\n> diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt\n> index 96767e7c75..13d37f96af 100644\n> --- a/Documentation/gitfaq.txt\n> +++ b/Documentation/gitfaq.txt\n> @@ -244,6 +244,37 @@ I asked Git to ignore various files, yet they are still tracked::\n> \tcategory, it is advised to use `git rm --cached ` as well as\n> \tadd these files/paths in the `.gitignore`.\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\n> +\tchanges as well as fetches any new changes from (if any). There\n> +\tmight 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\n> +\t\t case, the command to use is, `git remote set-url `.\n> +\n> +\t\t2. One might want to have two different remotes for fetching\n> +\t\t and pushing; this generally happens in case of triangular\n> +\t\t workflows: one fetches from one repository and pushes to\n> +\t\t another. In this case, it is advisable to have separate\n> +\t\t remotes for fetching and pushing. But, another way can be\n> +\t\t to change the push URL using the `--push` option in the\n> +\t\t `git set-url` command.\n> +\n> +\t\t3. One might want to push changes to a network protocol\n> +\t\t different from the one they fetch from. For instance,\n> +\t\t one may be using an unauthenticated http:// URL for\n> +\t\t fetching from a repository and use an ssh:// URL when\n> +\t\t you push via the same remote. In such a case, one can\n> +\t\t change the 'push' URL of the same remote using the `--push`\n> +\t\t option in `git remote set-url`. Now, the same remote will\n> +\t\t have two different kinds of URLs (http and ssh) for fetching\n> +\t\t and pulling.\n> ++\n> +One can list the remotes of a repository using `git remote -v` command.\n> +The default name of a remote is 'origin'.\n> +\n> Hooks\n> -----\n"},{"id":"395851","messageId":"xmqqy2qomwwl.fsf@gitster.c.googlers.com","threadId":"53273","inReplyTo":"20200421131223.29337-4-shouryashukla.oo@gmail.com","subject":"Re: [PATCH v3 3/4] gitfaq: shallow cloning a repository","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-04-21T20:00:42Z","receivedAt":"2020-04-21T20:00:50Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Shourya Shukla writes:\n\n> Add issue in 'Common issue' section which covers issues with cloning\n> large repositories. Use shallow cloning to clone the repository in\n> a smaller size.\n>\n> Signed-off-by: Shourya Shukla \n> ---\n> Documentation/gitfaq.txt | 14 ++++++++++++++\n> 1 file changed, 14 insertions(+)\n>\n> diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt\n> index 13d37f96af..cea293cf07 100644\n> --- a/Documentation/gitfaq.txt\n> +++ b/Documentation/gitfaq.txt\n> @@ -275,6 +275,20 @@ I want to change the remote of my repository. How do I do that?::\n> One can list the remotes of a repository using `git remote -v` command.\n> The default name of a remote is 'origin'.\n> \n> +[[shallow-cloning]]\n> +The repository I am trying to clone is too big. Is there an alternative\n> +way of cloning it in lesser space?::\n> +\tOne can clone a repository having a truncated history, meaning the\n> +\thistory\twill span upto a specified number of commits instead of\n> +\tthe whole history of the repository. This is called 'Shallow Cloning'.\n> ...\n\nThe question is worth keeping but the answer is questionable.\n\nI have a feeling that --depth/shallow is deprecated/frowned upon\nthese days and more people recommend partial/blob-less clones\ninstead (a few random people added to Cc: to see if they want to say\nsomething here). \n"},{"id":"395856","messageId":"011001d6181d$97301fc0$c5905f40$@nexbridge.com","threadId":"53273","inReplyTo":"xmqqy2qomwwl.fsf@gitster.c.googlers.com","subject":"RE: [PATCH v3 3/4] gitfaq: shallow cloning a repository","fromName":"Randall S. Becker","fromEmail":"rsbecker@nexbridge.com","sentAt":"2020-04-21T20:43:55Z","receivedAt":"2020-04-21T20:44:14Z","isPatch":true,"sender":{"key":"randall.becker@nexbridge.ca","avatar":"https://avatars.githubusercontent.com/u/28956764?v=4"},"body":"On April 21, 2020 4:01 PM, Junio C Hamano\n> Subject: Re: [PATCH v3 3/4] gitfaq: shallow cloning a repository\n> \n> Shourya Shukla writes:\n> \n> > Add issue in 'Common issue' section which covers issues with cloning\n> > large repositories. Use shallow cloning to clone the repository in a\n> > smaller size.\n> >\n> > Signed-off-by: Shourya Shukla \n> > ---\n> > Documentation/gitfaq.txt | 14 ++++++++++++++\n> > 1 file changed, 14 insertions(+)\n> >\n> > diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt index\n> > 13d37f96af..cea293cf07 100644\n> > --- a/Documentation/gitfaq.txt\n> > +++ b/Documentation/gitfaq.txt\n> > @@ -275,6 +275,20 @@ I want to change the remote of my repository.\n> How do I do that?::\n> > One can list the remotes of a repository using `git remote -v` command.\n> > The default name of a remote is 'origin'.\n> >\n> > +[[shallow-cloning]]\n> > +The repository I am trying to clone is too big. Is there an\n> > +alternative way of cloning it in lesser space?::\n> > +\tOne can clone a repository having a truncated history, meaning the\n> > +\thistory\twill span upto a specified number of commits instead of\n> > +\tthe whole history of the repository. This is called 'Shallow\nCloning'.\n> > ...\n> \n> The question is worth keeping but the answer is questionable.\n> \n> I have a feeling that --depth/shallow is deprecated/frowned upon these\ndays\n> and more people recommend partial/blob-less clones instead (a few random\n> people added to Cc: to see if they want to say something here).\n\nI rather hate to chime in as a dissenting opinion, but the --depth/shallow\nclone is very useful when git is being used as an artifact repository for\nproduction. The shallow clone allows only the production branch HEAD to be\ncloned into production/staging areas and limits the visible history for\nstaff who do not want to go through a potentially long trail during\ntime-sensitive operations (a.k.a. production installs). There are also space\nand policy constraints in some of these environments where they do not want\nto have ongoing visibility to non-production commit paths. When the *stuff*\nhits the fan, then it's good to be able to fetch everything (or a limited\nset). I would be very disappointed to see --depth frowned upon.\n\nRegards,\nRandall\n\n-- Brief whoami:\n NonStop developer since approximately 211288444200000000\n UNIX developer since approximately 421664400\n-- In my real life, I talk too much.\n\n\n\n"},{"id":"395861","messageId":"xmqq1rogmu9e.fsf@gitster.c.googlers.com","threadId":"53273","inReplyTo":"011001d6181d$97301fc0$c5905f40$@nexbridge.com","subject":"Re: [PATCH v3 3/4] gitfaq: shallow cloning a repository","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-04-21T20:57:49Z","receivedAt":"2020-04-21T20:57:57Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Randall S. Becker\" writes:\n\n>> I have a feeling that --depth/shallow is deprecated/frowned upon these\n> days\n>> and more people recommend partial/blob-less clones instead (a few random\n>> people added to Cc: to see if they want to say something here).\n>\n> I rather hate to chime in as a dissenting opinion,...\n\nOh, don't hate anything. It is greatly appreciated so that we can\ncover \"in such and such use case, this solution is good\" variants\nfor similarly-sounding-but-fundamentally-different classes of\nproblems. We do not want to give a spinal-reflex answer of \"use\nshallow\" (or \"use partial\", for that matter) to \"too large a repo\"\nquestion without contexts that guide the readers to a better choice.\n\nThat is where a well-organized FAQ list shines.\n\nThanks.\n"},{"id":"395866","messageId":"011501d61823$764f5180$62edf480$@nexbridge.com","threadId":"53273","inReplyTo":"xmqq1rogmu9e.fsf@gitster.c.googlers.com","subject":"RE: [PATCH v3 3/4] gitfaq: shallow cloning a repository","fromName":"Randall S. Becker","fromEmail":"rsbecker@nexbridge.com","sentAt":"2020-04-21T21:25:57Z","receivedAt":"2020-04-21T21:26:16Z","isPatch":true,"sender":{"key":"randall.becker@nexbridge.ca","avatar":"https://avatars.githubusercontent.com/u/28956764?v=4"},"body":"On April 21, 2020 4:58 PM, Junio C Hamano wrote:\n> Subject: Re: [PATCH v3 3/4] gitfaq: shallow cloning a repository\n> \"Randall S. Becker\" writes:\n> \n> >> I have a feeling that --depth/shallow is deprecated/frowned upon\n> >> these\n> > days\n> >> and more people recommend partial/blob-less clones instead (a few\n> >> random people added to Cc: to see if they want to say something here).\n> >\n> > I rather hate to chime in as a dissenting opinion,...\n> \n> Oh, don't hate anything. It is greatly appreciated so that we can cover\n\"in\n> such and such use case, this solution is good\" variants for\nsimilarly-sounding-\n> but-fundamentally-different classes of problems. We do not want to give a\n> spinal-reflex answer of \"use shallow\" (or \"use partial\", for that matter)\nto\n> \"too large a repo\"\n> question without contexts that guide the readers to a better choice.\n> \n> That is where a well-organized FAQ list shines.\n\nI have spoken on this topic and can probably share some of it.\n\n"},{"id":"395873","messageId":"CABPp-BEp-YVKCP7OFHjMgh+jQXgTWh11SHJmvTn847z3Owc1mg@mail.gmail.com","threadId":"53273","inReplyTo":"xmqqy2qomwwl.fsf@gitster.c.googlers.com","subject":"Re: [PATCH v3 3/4] gitfaq: shallow cloning a repository","fromName":"Elijah Newren","fromEmail":"newren@gmail.com","sentAt":"2020-04-22T00:13:18Z","receivedAt":"2020-04-22T00:14:30Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"On Tue, Apr 21, 2020 at 1:00 PM Junio C Hamano wrote:\n>\n> Shourya Shukla writes:\n>\n> > Add issue in 'Common issue' section which covers issues with cloning\n> > large repositories. Use shallow cloning to clone the repository in\n> > a smaller size.\n> >\n> > Signed-off-by: Shourya Shukla \n> > ---\n> > Documentation/gitfaq.txt | 14 ++++++++++++++\n> > 1 file changed, 14 insertions(+)\n> >\n> > diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt\n> > index 13d37f96af..cea293cf07 100644\n> > --- a/Documentation/gitfaq.txt\n> > +++ b/Documentation/gitfaq.txt\n> > @@ -275,6 +275,20 @@ I want to change the remote of my repository. How do I do that?::\n> > One can list the remotes of a repository using `git remote -v` command.\n> > The default name of a remote is 'origin'.\n> >\n> > +[[shallow-cloning]]\n> > +The repository I am trying to clone is too big. Is there an alternative\n> > +way of cloning it in lesser space?::\n> > + One can clone a repository having a truncated history, meaning the\n> > + history will span upto a specified number of commits instead of\n> > + the whole history of the repository. This is called 'Shallow Cloning'.\n> > ...\n>\n> The question is worth keeping but the answer is questionable.\n>\n> I have a feeling that --depth/shallow is deprecated/frowned upon\n> these days and more people recommend partial/blob-less clones\n> instead (a few random people added to Cc: to see if they want to say\n> something here).\n\nI don't have a problem with us saying we have to support shallow\nclones for years or decades more, but I personally strongly dislike\nadvertising it, for multiple reasons:\n\n* From an internal perspective: The shallow clone implementation feels\nlike a hack that isn't extensible and doesn't work with other\nfeatures, and as far as I can tell that's intrinsic to its design.\n\n* From an end-user perspective: Shallow clones are heavily misused,\noversold, and induce or perpetuate various misunderstandings. CI\nsystems seem especially keen on turning on shallow clones whether\nrequested or not and breaking all sorts of things from simple (like\n'git describe') to the more complex (like merge this branch with\nmaster and run tests there too to avoid breaks due to semantic\nconflicts) and all sorts of things inbetween (e.g. when trying to\n'debug with SSH' the user can't look around in the repo because it's\nall missing). Despite the huge waste of time projects induce by\ndefaulting this on and sometimes making it hard to turn off, is to\n'save space' and they often sell it as a dramatic savings. B if it's\na standard source code repository then usually you save only about 50%\nof the overall download size. (Years ago, I used to like to point out\nthat a git clone of a repo would only be marginally bigger than a svn\ncheckout, despite having 'all history', and had a handful of repos\nwhere I had measured the cost to back it up). The way CI folks talk\nabout shallow clone makes people assume that 'all history' is\nhundreds/thousands of times bigger than the most recent checkout. The\nonly case where 'saving size' seems to matter is either the special\nsimple cases that have really simple builds (though they tend to be\nsmall enough that the size doesn't matter anyway) or for repos that\nhave accidentally committed huge files in their history that are no\nlonger present in new versions. But because shallow clones are touted\nso much, people come to perceive the cost of 'all history' as being a\nvery onerous requirement in git. And the perception seems to be\nsticking in lots of places. I can sometimes go dig out facts for a\nrepository in question to show people the differences in sizes and\ndispel some of this, but that's a one-by-one case. I think these\nmisunderstandings hurt us as a community.\n\n* Diversion of resources: Even though there are current valid usecases\nfor shallow clones (e.g. Randall sounds like he has some), advertising\nthis feature is going to make it harder for us to focus efforts on the\nbetter designed solutions we want to implement and extend. Perhaps a\nfunny story is in order: At $FORMER_JOB, we made software used by\nvarious groups on supercomputers (or high performance computers, or\nhowever you want to refer to that class of many machines). One\ncustomer requested support on Itanium machines, and we made the\nnecessary (though painful) adjustments. At some point we decide to\nlist our supported platforms on the DVDs we sent out. Then at some\npoint, the Navy decides they're going to buy some nice\nsupercomputer(s). They want to use our software, but also want to use\ngeneral well-supported industry standard hardware. They put out a\npurchase order for $100 million (I don't remember the real number but\nit was large), and overlooked specifying the computer architecture.\nVendors who were just about to retire the very last Itanium chips and\nwere literally going to just scrap the rest of their inventory notice\nthis purchase order, bid on the procurement at dirt cheap prices, and\nthen the Navy is stuck because of \"don't waste taxpayer dollars\" and\n\"procurement has to be fair\". They need those machines to work for\nseveral years. Anyone who provides them software has to support that\narchitecture for several more years, but the vendors would not sell\nany more Itanium machines after that even if you begged, so we were\nworking with some really old Itanium machines that didn't have enough\npower to run the basic regression test in under 24 hours. The last\nsysadmin at $FORMER_JOB with the necessary qualifications to actually\nmaintain those systems (not just knowledge but red tape box checking\ntoo; this was government after all) was retiring about a year and a\nhalf before the mandatory support period ended for us as well. We\nfound out at some point that they checked our requirements before\nputting out the purchase order; had our DVDs only advertised support\nfor x86_64, the whole debacle could have been avoided.\n\nYes we totally need to support shallow clones (I brought them up as a\nconcern for fetch.writeCommitGraphs just last week after all), but I\nreally don't want to advertise them, and if we need to in some way,\nthen minimize it.\n\nAnyway, that's my $0.02.\n\nElijah\n"},{"id":"395877","messageId":"9142ccdb-6359-4936-e621-55eab980b7cd@gmail.com","threadId":"53273","inReplyTo":"011001d6181d$97301fc0$c5905f40$@nexbridge.com","subject":"Re: [PATCH v3 3/4] gitfaq: shallow cloning a repository","fromName":"Derrick Stolee","fromEmail":"stolee@gmail.com","sentAt":"2020-04-22T01:30:59Z","receivedAt":"2020-04-22T01:31:04Z","isPatch":true,"sender":{"key":"stolee@gmail.com","avatar":"https://avatars.githubusercontent.com/u/570044?v=4"},"body":"On 4/21/2020 4:43 PM, Randall S. Becker wrote:\n> On April 21, 2020 4:01 PM, Junio C Hamano\n>> Subject: Re: [PATCH v3 3/4] gitfaq: shallow cloning a repository\n>>\n>> Shourya Shukla writes:\n>>\n>>> Add issue in 'Common issue' section which covers issues with cloning\n>>> large repositories. Use shallow cloning to clone the repository in a\n>>> smaller size.\n>>>\n>>> Signed-off-by: Shourya Shukla \n>>> ---\n>>> Documentation/gitfaq.txt | 14 ++++++++++++++\n>>> 1 file changed, 14 insertions(+)\n>>>\n>>> diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt index\n>>> 13d37f96af..cea293cf07 100644\n>>> --- a/Documentation/gitfaq.txt\n>>> +++ b/Documentation/gitfaq.txt\n>>> @@ -275,6 +275,20 @@ I want to change the remote of my repository.\n>> How do I do that?::\n>>> One can list the remotes of a repository using `git remote -v` command.\n>>> The default name of a remote is 'origin'.\n>>>\n>>> +[[shallow-cloning]]\n>>> +The repository I am trying to clone is too big. Is there an\n>>> +alternative way of cloning it in lesser space?::\n>>> +\tOne can clone a repository having a truncated history, meaning the\n>>> +\thistory\twill span upto a specified number of commits instead of\n>>> +\tthe whole history of the repository. This is called 'Shallow\n> Cloning'.\n>>> ...\n>>\n>> The question is worth keeping but the answer is questionable.\n>>\n>> I have a feeling that --depth/shallow is deprecated/frowned upon these\n> days\n>> and more people recommend partial/blob-less clones instead (a few random\n>> people added to Cc: to see if they want to say something here).\n> \n> I rather hate to chime in as a dissenting opinion, but the --depth/shallow\n> clone is very useful when git is being used as an artifact repository for\n> production. \n\nIt is important, then, to mention what the _real_ uses for shallow clones.\n\nThey are great for getting just the working directory at tip for a throwaway\naction (like building an artifact, or just taking a static copy of something)\nbut it is a _terrible_ way to start working on source code for a project that\nyou intend to use for daily work.\n\nThe way this is worded in the FAQ will lead users to have a bad experience\nand we should recommend partial clone (--filter=blob:none) instead.\n\nOf course, with the speedups from reachability bitmaps, it is sometimes\n_faster_ to do a partial clone than a shallow clone. (It definitely takes\nless time in the \"counting objects\" phase, and the cost of downloading\nall commits and trees might be small enough on top of the necessary blob\ndata to keep the total cost under a shallow clone. Your mileage may vary.)\nBecause the cost of a partial clone is \"comparable\" to shallow clone, I\nwould almost recommend partial clone over shallow clones 95% of the time,\neven in scenarios like automated builds on cloud-hosted VMs.\n\nThanks,\n-Stolee\n"},{"id":"395881","messageId":"20200422040058.GB200999@google.com","threadId":"53273","inReplyTo":"9142ccdb-6359-4936-e621-55eab980b7cd@gmail.com","subject":"Re: [PATCH v3 3/4] gitfaq: shallow cloning a repository","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2020-04-22T04:00:58Z","receivedAt":"2020-04-22T04:01:07Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Derrick Stolee wrote:\n\n> Of course, with the speedups from reachability bitmaps, it is sometimes\n> _faster_ to do a partial clone than a shallow clone. (It definitely takes\n> less time in the \"counting objects\" phase, and the cost of downloading\n> all commits and trees might be small enough on top of the necessary blob\n> data to keep the total cost under a shallow clone. Your mileage may vary.)\n> Because the cost of a partial clone is \"comparable\" to shallow clone, I\n> would almost recommend partial clone over shallow clones 95% of the time,\n> even in scenarios like automated builds on cloud-hosted VMs.\n\nBy the way, an idea for the interested (#leftoverbits?):\n\nIt would be possible to emulate the shallow clone experience making\nuse of the partial clone protocol. That is, fetch a full history\nwithout blobs but record the \"shallows\" somewhere and make user-facing\ntraversals like \"git log\" stop there (similar to the effect \"git\nreplace\" has on user-facing traversals). Then later fetches would be\nable to take advantage of the full commit history, but scripts and\nmuscle memory (e.g., the assumption that most commands will never\ncontact the remote) that assume a shallow clone would continue to\nwork.\n\nWould that be useful or interesting to people?\n\nThanks,\nJonathan\n"},{"id":"396359","messageId":"20200427173049.GA6714@konoha","threadId":"53273","inReplyTo":"xmqq368wobqu.fsf@gitster.c.googlers.com","subject":"Re: [PATCH v3 2/4] gitfaq: changing the remote of a repository","fromName":"Shourya Shukla","fromEmail":"shouryashukla.oo@gmail.com","sentAt":"2020-04-27T17:30:49Z","receivedAt":"2020-04-27T17:30:58Z","isPatch":true,"sender":{"key":"shouryashukla.oo@gmail.com","avatar":"https://avatars.githubusercontent.com/u/43680618?v=4"},"body":"On 21/04 12:54, Junio C Hamano wrote:\n> Shourya Shukla writes:\n> \n> > Add issue in 'Common Issues' section which addresses the problem of\n> > changing the remote of a repository, covering various cases in which\n> > one might want to change the remote and the ways to do the same.\n> >\n> > Signed-off-by: Shourya Shukla \n> > ---\n> > Documentation/gitfaq.txt | 31 +++++++++++++++++++++++++++++++\n> > 1 file changed, 31 insertions(+)\n> \n> Again, I think this belongs to Documentation/git-remote.txt; unlike\n> the \".gitignore\" one, however, the existing description is heavily\n> concentrated on \"what happens when X is set to Y?\" and does not\n> answer \"why would I want to set X to Y in the first place?\" very\n> much. And the text below you have is a good thing to teach anybody\n> who learns \"git-remote\". \n> \n> So how about clarifying the existing page, perhaps its DISCUSSION\n> section (which currently talks only about \"how to add a remote, and\n> configure\" without discussing \"why would I want to add a remote, set\n> a URL and/or a pushURL to it\") with what you have, and trim the\n> description here in the FAQ file to the minimum and refer to the\n> page instead?\n\nYep, it seems reasonable. So a good strategy would be to append the\n'DISCUSSION' section with what I have added in the FAQ and quoting a\ncouple of lines from the documentation, providing the solution and\ngiving a further reference to the Documentation right?\n\n\tA remote is an identifier for a location to which Git pushes\n\tyour changes as well as fetches any new changes from (if any).\n\n\tTo change the remote of your repository, you may want to\n\texecute:\n\t\tgit remote set-url \n\nSomething along the above lines? I think that a generic user will mostly\nfind this as a solution to their problem instead of using the '--push'\noption to specify a different push URL.\n"}]}