{"thread":{"id":"53000","subject":"[PATCH 0/1] FAQ for common user questions","startedAt":"2020-03-15T22:45:07Z","lastAt":"2020-03-19T23:49:42Z","messageCount":9,"participants":["brian m. carlson","Junio C Hamano","Emily Shaffer","Shourya Shukla"],"isPatch":true,"patchVersion":1,"patchTotal":1},"messages":[{"id":"393286","messageId":"20200315223923.170371-1-sandals@crustytoothpaste.net","threadId":"53000","inReplyTo":null,"subject":"[PATCH 0/1] FAQ for common user questions","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2020-03-15T22:39:22Z","receivedAt":"2020-03-15T22:45:07Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"Git is an enormously flexible and power piece of software, but many\npeople find it confusing and hard to use.  Over the time I've been\ncontributing, I've noticed a lot of the same questions keep coming up\nover and over.  Some of these questions are well answered by existing\ndocumentation, but people have trouble finding it.  Others are not\nanswered, and still others are questions about integrating with common\ntools and hosting platforms.\n\nTo help people find and discover this documentation, let's provide a FAQ\nthat covers common issues.  A lot of these issues are things I've seen\nasked on Stack Overflow or elsewhere and we'd be doing everyone a\nservice if we included some stock answers in one place in our\ndocumentation.\n\nThe FAQ is designed to be conversational, approachable, and geared\ntowards a competent novice user.  However, it also addresses questions\nthat I've seen from technically advanced colleagues.  I've tried to make\nit address common questions about integrations with other tools, such as\nCI systems and hosting platforms, without mentioning any specific tool\nby name.  This keeps us neutral on particular tools, but recognizes that\nthese tools are a common part of people's development experiences.\n\nI definitely think we'll add more questions as we go along, but this\nseems like a reasonable start for now.  I'd love feedback about the\nphrasing of questions or answers, anything I've missed, and anything\nthat might be technically inaccurate, especially about Windows.\n\nbrian m. carlson (1):\n  docs: add a FAQ\n\n Documentation/Makefile   |   1 +\n Documentation/gitfaq.txt | 330 +++++++++++++++++++++++++++++++++++++++\n 2 files changed, 331 insertions(+)\n create mode 100644 Documentation/gitfaq.txt\n\n"},{"id":"393287","messageId":"20200315223923.170371-2-sandals@crustytoothpaste.net","threadId":"53000","inReplyTo":"20200315223923.170371-1-sandals@crustytoothpaste.net","subject":"[PATCH 1/1] docs: add a FAQ","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2020-03-15T22:39:23Z","receivedAt":"2020-03-15T22:45:07Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"Git is an enormously flexible and powerful piece of software.  However,\nit can be intimidating for many users and there are a set of common\nquestions that users often ask.  While we already have some new user\ndocumentation, it's worth adding a FAQ to address common questions that\nusers often have.  Even though some of this is addressed elsewhere in\nthe documentation, experience has shown that it is difficult for users\nto find, so a centralized location is helpful.\n\nAdd such a FAQ and fill it with some common questions and answers.\nWhile there are few entries now, we can expand it in the future to cover\nmore things as we find new questions that users have.  Let's also add\nsection markers so that people answering questions can directly link\nusers to the proper answer.\n\nThe FAQ also addresses common configuration questions that apply not\nonly to Git as an independent piece of software but also the ecosystem\nof CI tools and hosting providers that people use, since these are the\nsource of common questions.  An attempt has been made to avoid\nmentioning any particular provider or tool, but to nevertheless cover\ncommon configurations that apply to a wide variety of such tools.\n\nNote that the long lines for certain questions are required, since\nAsciidoctor does not permit broken lines there.\n---\n Documentation/Makefile   |   1 +\n Documentation/gitfaq.txt | 330 +++++++++++++++++++++++++++++++++++++++\n 2 files changed, 331 insertions(+)\n create mode 100644 Documentation/gitfaq.txt\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 8fe829cc1b..59e6ce3a2a 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -30,6 +30,7 @@ MAN7_TXT += gitcredentials.txt\n MAN7_TXT += gitcvs-migration.txt\n MAN7_TXT += gitdiffcore.txt\n MAN7_TXT += giteveryday.txt\n+MAN7_TXT += gitfaq.txt\n MAN7_TXT += gitglossary.txt\n MAN7_TXT += gitnamespaces.txt\n MAN7_TXT += gitremote-helpers.txt\ndiff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt\nnew file mode 100644\nindex 0000000000..318e4dd648\n--- /dev/null\n+++ b/Documentation/gitfaq.txt\n@@ -0,0 +1,330 @@\n+gitfaq(7)\n+=========\n+\n+NAME\n+----\n+gitfaq - Frequently asked questions about using Git\n+\n+SYNOPSIS\n+--------\n+gitfaq\n+\n+DESCRIPTION\n+-----------\n+\n+The examples in this FAQ assume a standard POSIX shell, like `bash` or `dash`,\n+and a user, A U Thor, who has the account `author` on the hosting provider\n+`git.example.org`.\n+\n+Configuration\n+-------------\n+\n+[[user-name]]\n+What should I put in `user.name`?::\n+  You should put your personal name; that is, the name that other humans call\n+\tyou.  This will be the name portion that is stored in every commit you make.\n++\n+This configuration doesn't have any effect on authenticating to remote\n+services; for that, see `credential.username` in linkgit:git-config[1].\n+\n+[[http-postbuffer]]\n+What does `http.postBuffer` really do?::\n+\tThis option changes the size of the buffer that Git uses when pushing data to\n+\ta remote over HTTP or HTTPS.  If the data is larger than this size, libcurl,\n+\twhich handles the HTTP support for Git, will use chunked transfer encoding\n+\tsince it isn't known ahead of time what the size of the pushed data will be.\n++\n+Leaving this value at the default size is fine unless you know that either the\n+remote server or a proxy in the middle doesn't support HTTP/1.1 (which\n+introduced the chunked transfer encoding) or is known to be broken with chunked\n+data.  People often suggest this as a solution for generic push problems, but\n+since almost every server and proxy supports at least HTTP/1.1, raising this\n+value usually doesn't solve most push problems.  A server or proxy that didn't\n+correctly support HTTP/1.1 and chunked transfer encoding wouldn't be that useful\n+on the Internet today, since it would break lots of traffic.\n++\n+Note that increasing this value will increase the memory used on every relevant\n+push that Git does over HTTP or HTTPS, since the entire buffer is allocated\n+regardless of whether or not it is all used.  Thus, it's best to leave it at the\n+default unless you are sure you need a different value.\n+\n+[[configure-editor]]\n+How do I configure a different editor?::\n+\tIf you haven't specified an editor specifically for Git, it will by default\n+\tuse the editor you've configured using the `VISUAL` or `EDITOR` environment\n+\tvariables, or if neither is specified, the system default (which is usually\n+\t`vi`).  Since some people find `vi` difficult to use, it may be desirable to\n+\tchange the editor used.\n++\n+If you want to configure a general editor for most programs which need one, you\n+can edit your shell configuration (e.g., `~/.bashrc` or `~/.zshenv`) to contain\n+a line setting the `EDITOR` or `VISUAL` environment variable to an appropriate\n+value.  For example, if you preferred the editor `nano`, then you could write\n+the following:\n++\n+----\n+export VISUAL=nano\n+----\n++\n+If you want to configure an editor specifically for Git, you can either set the\n+`core.editor` configuration value or the `GIT_EDITOR` environment variable.  You\n+can see linkgit:git-var[1] for details on the order in which these options are\n+consulted.\n++\n+Note that in all cases, the editor value will be passed to the shell, so any\n+arguments containing spaces should be appropriately quoted.  Additionally, if\n+your editor normally detaches from the terminal when invoked, you should specify\n+it with an argument that makes it not do that, or else Git will not see any\n+changes.  An example of a configuration addressing both of these issues on\n+Windows would be the configuration `\"C:\\Program Files\\Vim\\gvim.exe\" --nofork`,\n+which quotes the filename with spaces and specifies the `--nofork` option to\n+avoid backgrounding the process.\n+\n+Credentials\n+-----------\n+\n+[[http-credentials]]\n+How do I specify my credentials when pushing over HTTP?::\n+\tThe easiest way to do this is to use a credential helper via the\n+\t`credential.helper` configuration.  Most systems provide a standard choice to\n+\tintegrate with the system credential manager.  For example, Git for Windows\n+\tprovides the `wincred` credential manager, macOS has the `osxkeychain`\n+\tcredential manager, and Unix systems with a standard desktop environment can\n+\tuse the `libsecret` credential manager.  All of these store credentials in an\n+\tencrypted store to keep your passwords or tokens secure.\n++\n+In addition, you can use the `store` credential manager which stores in a file\n+in your home directory, or the `cache` credential manager, which does not\n+permanently store your credentials, but does prevent you from being prompted for\n+them for a certain period of time.\n++\n+You can also just enter your password when prompted, or you can place the\n+password (which must be percent-encoded) in the URL.  The latter option is not\n+particularly secure and can lead to accidental exposure of credentials, so it is\n+not recommended.\n+\n+[[http-credentials-environment]]\n+How do I read a password or token from an environment variable?::\n+  The `credential.helper` configuration option can also take an arbitrary shell\n+\tcommand that produces the credential protocol on standard output.  This is\n+\tuseful when passing credentials into a container, for example.\n++\n+Such a shell command can be specified by starting the option value with an\n+exclamation point.  If your password or token were stored in the `GIT_TOKEN`,\n+you could run the following command to set your credential helper:\n++\n+----\n+$ git config credential.helper \\\n+\t'!f() { echo username=author; echo \"password=$GIT_TOKEN\"; };f'\n+----\n+\n+[[http-reset-credentials]]\n+How do I change the password or token I've saved in my credential manager?::\n+\tUsually, if the password or token is invalid, Git will erase it and prompt for\n+\ta new one.  However, there are times when this doesn't always happen.  To\n+\tchange the password or token, you can erase the existing credentials and then\n+\tGit will prompt for new ones.  To erase credentials, use a syntax like the\n+\tfollowing (substituting your username and the hostname):\n++\n+----\n+$ echo url=https://author@git.example.org | git credential reject\n+----\n+\n+[[multiple-accounts-http]]\n+How do I use multiple accounts with the same hosting provider using HTTP?::\n+  Usually the easiest way to distinguish between these accounts is to use the\n+\tusername in the URL.  For example, if you have the accounts `author` and\n+\t`committer` on `git.example.org`, you can use the URLs\n+\thttps://author@git.example.org/org1/project1.git and\n+\thttps://committer@git.example.org/org2/project2.git.  This way, when you use a\n+\tcredential helper, it will automatically try to look up the correct\n+\tcredentials for your account.  If you already have a remote set up, you can\n+\tchange the URL with something like `git remote set-url origin\n+\thttps://author@git.example.org/org1/project1.git` (see linkgit:git-remote[1]\n+\tfor details).\n+\n+[[multiple-accounts-ssh]]\n+How do I use multiple accounts with the same hosting provider using SSH?::\n+\tWith most hosting providers that support SSH, a single key pair uniquely\n+\tidentifies a user.  Therefore, to use multiple accounts, it's necessary to\n+\tcreate a key pair for each account.  If you're using a reasonably modern\n+\tOpenSSH version, you can create a new key pair with something like `ssh-keygen\n+\t-t ed25519 -f ~/.ssh/id_committer`.  You can then register the public key (in\n+\tthis case, `~/.ssh/id_committer.pub`; note the `.pub`) with the hosting\n+\tprovider.\n++\n+Most hosting providers use a single SSH account for pushing; that is, all users\n+push to the `git` account (e.g., `git@git.example.org`).  If that's the case for\n+your provider, you can set up multiple aliases in SSH to make it clear which key\n+pair to use.  For example, you could write something like the following,\n+substituting the proper private key file:\n++\n+----\n+# This is the account for author on git.example.org.\n+Host example_author\n+   HostName git.example.org\n+\t User git\n+\t # This is the key pair registered for author with git.example.org.\n+\t IdentityFile ~/.ssh/id_author\n+\t IdentitiesOnly yes\n+# This is the committer for author on git.example.org.\n+Host example_committer\n+   HostName git.example.org\n+\t User git\n+\t # This is the key pair registered for committer with git.example.org.\n+\t IdentityFile ~/.ssh/id_committer\n+\t IdentitiesOnly yes\n+----\n++\n+Then, you can adjust your push URL to use `git@example_author` or\n+`git@example_committer` instead of `git@example.org` (e.g., `git remote set-url\n+git@example_author:org1/project1.git`).\n+\n+Common Issues\n+-------------\n+\n+[[last-commit-amend]]\n+I've made a mistake in the last commit.  How do I change it?::\n+\tYou can make the appropriate change to your working tree, run `git add <file>`\n+\tto stage it, and then `git commit --amend`.  Your change will be included in\n+\tthe commit, and you'll be prompted to edit the commit message again; if you\n+\tdon't want to edit it, you can use the `--no-edit` option to `git commit` in\n+\taddition, or just save and quit when your editor opens.\n+\n+[[undo-previous-change]]\n+I've made a change with a bug and it's been included in the main branch.  How should I undo it?::\n+\tThe usual way to deal with this is to use `git revert`.  This preserves the\n+\thistory that the original change was made and was a valuable contribution, but\n+\talso introduces a new commit that undoes those changes because the original\n+\thad a problem.  The commit message of the revert indicates the commit which\n+\twas reverted and can be edited to include an explanation as to why the revert\n+\twas made.\n+\n+[[ignore-tracked-files]]\n+How do I ignore changes to a tracked file?::\n+  Git doesn't provide a way to do this.  The reason is that if Git needs to\n+\toverwrite this file, such as during a checkout, it doesn't know whether the\n+\tchanges to the file are precious and should be kept, or whether they are\n+\tirrelevant and can safely be destroyed.  Therefore, it has to take the safe\n+\troute and always preserve them.\n++\n+Some people are tempted to use certain features of `git update-index`, namely\n+the assume-unchanged and skip-worktree bits, but these don't work properly for\n+this purpose and shouldn't be used this way.\n++\n+If your goal is to modify a configuration file, it can often be helpful to have\n+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+Hooks\n+-----\n+\n+[[restrict-with-hooks]]\n+How do I prevent users from making certain changes with hooks?::\n+\tThe only safe place to make these changes is on the remote repository (i.e.,\n+\tthe Git server), usually in the `pre-receive` hook or in a continuous\n+\tintegration (CI) system.  These are the locations in which policy can be\n+\tenforced effectively.\n++\n+Some people try to use `pre-commit` hooks (or, for commit messages, `commit-msg`\n+hooks) to check these things, which is fine if you're working as a solo\n+developer and want the tooling to help you.  However, using hooks on a developer\n+machine is not effective as a policy control because a user can bypass these\n+hooks with `--no-verify` without being noticed (among various other ways).  Git\n+assumes that the user is in control of their local repositories and doesn't try\n+to prevent this or tattle on the user.\n++\n+In addition, some advanced users find `pre-commit` hooks to be an impediment to\n+workflows that use temporary commits to stage work in progress or that create\n+fixup commits, so it's better to push these kinds of checks to the server\n+anyway.\n+\n+Cross-Platform Issues\n+~~~~~~~~~~~~~~~~~~~~~\n+\n+[[windows-text-binary]]\n+I'm on Windows and my text files are detected as binary.::\n+\tGit works best when you store text files as UTF-8.  Many programs on Windows\n+\tsupport UTF-8, but some do not and only use the little-endian UTF-16 format,\n+\twhich Git detects as binary.  If you can't use UTF-8 with your programs, you\n+\tcan specify a working tree encoding that indicates which encoding your files\n+\tshould be checked out with, while still storing these files as UTF-8 in the\n+\trepository.  This allows tools like linkgit:git-diff[1] to work as expected,\n+\twhile still allowing your tools to work.\n++\n+To do so, you can specify a linkgit:gitattributes[5] pattern with with the\n+`working-tree-encoding` attribute.  For example, the following pattern sets all\n+C files to use UTF-16LE-BOM, which is a common encoding on Windows:\n++\n+----\n+*.c\tworking-tree-encoding=UTF-16LE-BOM\n+----\n++\n+You will need to run `git add --renormalize` to have this take effect.  Note\n+that if you are making these changes on a project that is used across platforms,\n+you'll probably want to make it in a per-user configuration file or in the one\n+in `$GIT_DIR/info/attributes`, since making it in a `.gitattributes` file in\n+the repository will apply to all users of the repository.\n++\n+See the following entry for information about normalizing line endings as well,\n+and see linkgit:gitattributes[5] for more information about attribute files.\n+\n+[[windows-diff-control-m]]\n+I'm on Windows and git diff shows my files as having a `^M` at the end.::\n+\tBy default, Git expects files to be stored with Unix line endings.  As such,\n+\tthe carriage return (`^M`) that is part of a Windows line ending results is\n+\tshow because it is considered to be trailing whitespace.  Git defaults to\n+\tshowing trailing whitespace only on new lines, not existing ones.\n++\n+You can store the files in the repository with Unix line endings and convert\n+them automatically to your platform's line endings.  To do that, set the\n+configuration option `core.eol` to `native` and see the following entry for\n+information about how to configure files as text or binary.\n++\n+You can also control this behavior with the `core.whitespace` setting if you\n+don't wish to remove the carriage returns from your line endings.\n+\n+[[recommended-storage-settings]]\n+What's the recommended way to store files in Git?::\n+\tWhile Git can store and handle any file of any type, there are some settings\n+\tthat work better than others.  In general, we recommend that text files be\n+\tstored in UTF-8 without a byte-order mark (BOM) with LF (Unix-style) endings.\n+\tWe also recommend the use of UTF-8 (again, without BOM) in commit messages.\n+\tThese are the settings that work best across platforms and with tools such as\n+\t`git diff` and `git merge`.\n++\n+Additionally, if you have a choice between storage formats that are text based\n+or non-text based, we recommend storing files in the text format and, if\n+necessary, transforming them into the other format.  For example, a text-based\n+SQL dump with one record per line will work much better for diffing and merging\n+than an actual database file.  Similarly, text-based formats such as Markdown\n+and AsciiDoc will work better than binary formats such as Microsoft Word and\n+PDF.\n++\n+Similarly, storing binary dependencies (e.g., shared libraries or JAR files) or\n+build products in the repository is generally not recommended.  Dependencies and\n+build products are best stored on an artifact or package server with only\n+references, URLs, and hashes stored in the repository.\n++\n+We also recommend setting a link:gitattributes[5] file to explicitly mark which\n+files are text and which are binary.  If you want Git to guess, you can set the\n+attribute `text=auto`.  For example, the following might be appropriate in some\n+projects:\n++\n+----\n+# By default, guess.\n+*\t\t\ttext=auto\n+# Mark all C files as text.\n+*.c\t\ttext\n+# Mark all JPEG files as binary.\n+*.jpg\tbinary\n+----\n++\n+These settings help tools pick the right format for output such as patches and\n+result in files being checked out in the appropriate line ending for the\n+platform.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\n"},{"id":"393289","messageId":"xmqqa74h9oqd.fsf@gitster.c.googlers.com","threadId":"53000","inReplyTo":"20200315223923.170371-2-sandals@crustytoothpaste.net","subject":"Re: [PATCH 1/1] docs: add a FAQ","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-03-15T23:34:34Z","receivedAt":"2020-03-15T23:34:46Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"brian m. carlson\" <sandals@crustytoothpaste.net> writes:\n\n> Note that the long lines for certain questions are required, since\n> Asciidoctor does not permit broken lines there.\n\nI didn't see \"long lines\", but was puzzled by a few lines with\nununiform indentation.\n\n> +Configuration\n> +-------------\n> +\n> +[[user-name]]\n> +What should I put in `user.name`?::\n> +  You should put your personal name; that is, the name that other humans call\n> +\tyou.  This will be the name portion that is stored in every commit you make.\n\nShouldn't the first line \"You should put ...\" be indented to the\nsame level as the second line, like the entry for http-postbuffer we\nsee below?\n\n> ++\n> +This configuration doesn't have any effect on authenticating to remote\n> +services; for that, see `credential.username` in linkgit:git-config[1].\n> +\n> +[[http-postbuffer]]\n> +What does `http.postBuffer` really do?::\n> +\tThis option changes the size of the buffer that Git uses when pushing data to\n> +\ta remote over HTTP or HTTPS.  If the data is larger than this size, libcurl,\n> ...\n\n> +[[http-credentials-environment]]\n> +How do I read a password or token from an environment variable?::\n> +  The `credential.helper` configuration option can also take an arbitrary shell\n\nLikewise.\n\n> +[[multiple-accounts-http]]\n> +How do I use multiple accounts with the same hosting provider using HTTP?::\n> +  Usually the easiest way to distinguish between these accounts is to use the\n\nLikewise.\n\n> +Most hosting providers use a single SSH account for pushing; that is, all users\n> +push to the `git` account (e.g., `git@git.example.org`).  If that's the case for\n> +your provider, you can set up multiple aliases in SSH to make it clear which key\n> +pair to use.  For example, you could write something like the following,\n> +substituting the proper private key file:\n> ++\n> +----\n> +# This is the account for author on git.example.org.\n> +Host example_author\n> +   HostName git.example.org\n> +\t User git\n\nHere, shouldn't HostName entry be indented the same way as User and\nother entries for this \"Host\" entry?\n\n> +\t # This is the key pair registered for author with git.example.org.\n> +\t IdentityFile ~/.ssh/id_author\n> +\t IdentitiesOnly yes\n> +# This is the committer for author on git.example.org.\n> +Host example_committer\n> +   HostName git.example.org\n\nLikewise.\n\n> +Common Issues\n> +-------------\n> +\n> +[[last-commit-amend]]\n> +I've made a mistake in the last commit.  How do I change it?::\n> +\tYou can make the appropriate change to your working tree, run `git add <file>`\n> +\tto stage it, and then `git commit --amend`.  Your change will be included in\n> +\tthe commit, and you'll be prompted to edit the commit message again; if you\n> +\tdon't want to edit it, you can use the `--no-edit` option to `git commit` in\n> +\taddition, or just save and quit when your editor opens.\n\nWhen the undesired part of the last change was \"I added a junk\nfile\", then instead of `git add`, `git rm [--cached]` would become\nnecessary.\n\nI personally would prefer to say \"if you want to use the original\ncommit message verbatim\" instead of \"you do not want to edit\", but\nit may be just me.  I just find the document to give more positive\nattitude if it avoids phrasing end-users' wishes in terms of what\nthey do not want to do.\n\n> +[[undo-previous-change]]\n> +I've made a change with a bug and it's been included in the main branch.  How should I undo it?::\n> +\tThe usual way to deal with this is to use `git revert`.  This preserves the\n> +\thistory that the original change was made and was a valuable contribution, but\n> +\talso introduces a new commit that undoes those changes because the original\n> +\thad a problem.  The commit message of the revert indicates the commit which\n> +\twas reverted and can be edited to include an explanation as to why the revert\n> +\twas made.\n\nCan we phrase \"and can be edited\" in a bit more opinionated way?\nThe users are encouraged to describe why and that is why we open an\neditor by default for them to do so.\n\n> +[[ignore-tracked-files]]\n> +How do I ignore changes to a tracked file?::\n> +  Git doesn't provide a way to do this.  The reason is that if Git needs to\n> +\toverwrite this file, such as during a checkout, it doesn't know whether the\n\nIndentation.\n\n> +----\n> +# By default, guess.\n> +*\t\t\ttext=auto\n> +# Mark all C files as text.\n> +*.c\t\ttext\n> +# Mark all JPEG files as binary.\n> +*.jpg\tbinary\n> +----\n\nThe first entry text=auto is indented more deeply than others.  Intended?\n\nThanks.\n"},{"id":"393291","messageId":"20200316001329.GB6910@camp.crustytoothpaste.net","threadId":"53000","inReplyTo":"xmqqa74h9oqd.fsf@gitster.c.googlers.com","subject":"Re: [PATCH 1/1] docs: add a FAQ","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2020-03-16T00:13:29Z","receivedAt":"2020-03-16T00:13:37Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2020-03-15 at 23:34:34, Junio C Hamano wrote:\n> \"brian m. carlson\" <sandals@crustytoothpaste.net> writes:\n> \n> > Note that the long lines for certain questions are required, since\n> > Asciidoctor does not permit broken lines there.\n> \n> I didn't see \"long lines\", but was puzzled by a few lines with\n> ununiform indentation.\n\nI'll fix all that.  Apparently somewhere along the line my editor got\nconfused and inserted two spaces (which is my typical AsciiDoc\nconfiguration) instead of a tab (which is what I've configured for Git\nfiles).\n\n> > +Common Issues\n> > +-------------\n> > +\n> > +[[last-commit-amend]]\n> > +I've made a mistake in the last commit.  How do I change it?::\n> > +\tYou can make the appropriate change to your working tree, run `git add <file>`\n> > +\tto stage it, and then `git commit --amend`.  Your change will be included in\n> > +\tthe commit, and you'll be prompted to edit the commit message again; if you\n> > +\tdon't want to edit it, you can use the `--no-edit` option to `git commit` in\n> > +\taddition, or just save and quit when your editor opens.\n> \n> When the undesired part of the last change was \"I added a junk\n> file\", then instead of `git add`, `git rm [--cached]` would become\n> necessary.\n\nGood point.  I'll mention `git add` or `git rm` as appropriate.\n\n> I personally would prefer to say \"if you want to use the original\n> commit message verbatim\" instead of \"you do not want to edit\", but\n> it may be just me.  I just find the document to give more positive\n> attitude if it avoids phrasing end-users' wishes in terms of what\n> they do not want to do.\n\nThanks.  This is great feedback.\n\n> > +[[undo-previous-change]]\n> > +I've made a change with a bug and it's been included in the main branch.  How should I undo it?::\n> > +\tThe usual way to deal with this is to use `git revert`.  This preserves the\n> > +\thistory that the original change was made and was a valuable contribution, but\n> > +\talso introduces a new commit that undoes those changes because the original\n> > +\thad a problem.  The commit message of the revert indicates the commit which\n> > +\twas reverted and can be edited to include an explanation as to why the revert\n> > +\twas made.\n> \n> Can we phrase \"and can be edited\" in a bit more opinionated way?\n> The users are encouraged to describe why and that is why we open an\n> editor by default for them to do so.\n\nYes, I agree that we want to encourage a helpful commit message here.  Will update.\n-- \nbrian m. carlson: Houston, Texas, US\nOpenPGP: https://keybase.io/bk2204\n"},{"id":"393426","messageId":"20200318230030.GA45325@google.com","threadId":"53000","inReplyTo":"20200315223923.170371-2-sandals@crustytoothpaste.net","subject":"Re: [PATCH 1/1] docs: add a FAQ","fromName":"Emily Shaffer","fromEmail":"emilyshaffer@google.com","sentAt":"2020-03-18T23:00:30Z","receivedAt":"2020-03-18T23:00:42Z","isPatch":true,"sender":{"key":"nasamuffin@google.com","avatar":"https://avatars.githubusercontent.com/u/1606826?v=4"},"body":"On Sun, Mar 15, 2020 at 10:39:23PM +0000, brian m. carlson wrote:\n> Git is an enormously flexible and powerful piece of software.  However,\n> it can be intimidating for many users and there are a set of common\n> questions that users often ask.  While we already have some new user\n> documentation, it's worth adding a FAQ to address common questions that\n> users often have.  Even though some of this is addressed elsewhere in\n> the documentation, experience has shown that it is difficult for users\n> to find, so a centralized location is helpful.\n\nIt's true that some of it is duplicated; if we're worried about the info\ngetting out of sync, we might be able to do something like\nDocumentation/config so we're pulling in a single piece of text to both\nplaces.\n\n> \n> Add such a FAQ and fill it with some common questions and answers.\n> While there are few entries now, we can expand it in the future to cover\n> more things as we find new questions that users have.  Let's also add\n> section markers so that people answering questions can directly link\n> users to the proper answer.\n> \n> The FAQ also addresses common configuration questions that apply not\n> only to Git as an independent piece of software but also the ecosystem\n> of CI tools and hosting providers that people use, since these are the\n> source of common questions.  An attempt has been made to avoid\n> mentioning any particular provider or tool, but to nevertheless cover\n> common configurations that apply to a wide variety of such tools.\n> \n> Note that the long lines for certain questions are required, since\n> Asciidoctor does not permit broken lines there.\n> ---\n>  Documentation/Makefile   |   1 +\n>  Documentation/gitfaq.txt | 330 +++++++++++++++++++++++++++++++++++++++\n>  2 files changed, 331 insertions(+)\n>  create mode 100644 Documentation/gitfaq.txt\n> \n> diff --git a/Documentation/Makefile b/Documentation/Makefile\n> index 8fe829cc1b..59e6ce3a2a 100644\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n> @@ -30,6 +30,7 @@ MAN7_TXT += gitcredentials.txt\n>  MAN7_TXT += gitcvs-migration.txt\n>  MAN7_TXT += gitdiffcore.txt\n>  MAN7_TXT += giteveryday.txt\n> +MAN7_TXT += gitfaq.txt\n>  MAN7_TXT += gitglossary.txt\n>  MAN7_TXT += gitnamespaces.txt\n>  MAN7_TXT += gitremote-helpers.txt\n> diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt\n> new file mode 100644\n> index 0000000000..318e4dd648\n> --- /dev/null\n> +++ b/Documentation/gitfaq.txt\n> @@ -0,0 +1,330 @@\n> +gitfaq(7)\n> +=========\n> +\n> +NAME\n> +----\n> +gitfaq - Frequently asked questions about using Git\n> +\n> +SYNOPSIS\n> +--------\n> +gitfaq\n> +\n> +DESCRIPTION\n> +-----------\n> +\n> +The examples in this FAQ assume a standard POSIX shell, like `bash` or `dash`,\n> +and a user, A U Thor, who has the account `author` on the hosting provider\n> +`git.example.org`.\n> +\n> +Configuration\n> +-------------\n> +\n> +[[user-name]]\n> +What should I put in `user.name`?::\n> +  You should put your personal name; that is, the name that other humans call\n> +\tyou.  This will be the name portion that is stored in every commit you make.\n\nI like the direction but I think it is still a little unclear. Other\nhumans call me Emily, but I want to put \"Emily Shaffer\" in my user.name.\nI wonder how we can suggest full name in a way that's as universal as\n\"the name that other humans call you\"? I think I got around to this\npoint by using examples when covering the SOB in MyFirstContribution, so\nI don't have a good answer off the top of my head.\n\n> ++\n> +This configuration doesn't have any effect on authenticating to remote\n> +services; for that, see `credential.username` in linkgit:git-config[1].\n> +\n> +[[http-postbuffer]]\n> +What does `http.postBuffer` really do?::\n> +\tThis option changes the size of the buffer that Git uses when pushing data to\n> +\ta remote over HTTP or HTTPS.  If the data is larger than this size, libcurl,\n> +\twhich handles the HTTP support for Git, will use chunked transfer encoding\n> +\tsince it isn't known ahead of time what the size of the pushed data will be.\n> ++\n> +Leaving this value at the default size is fine unless you know that either the\n> +remote server or a proxy in the middle doesn't support HTTP/1.1 (which\n> +introduced the chunked transfer encoding) or is known to be broken with chunked\n> +data.  People often suggest this as a solution for generic push problems, but\n> +since almost every server and proxy supports at least HTTP/1.1, raising this\n> +value usually doesn't solve most push problems.  A server or proxy that didn't\n\nThis might be burying the lede a little for someone frantically skimming\nfor an answer. If I was really spinning my wheels I might read \"People\noften suggest this as a solution for generic push problems\" and go try\nit. Is \"People often (erroneously) suggest this ...\" too verbose?\n\n> +correctly support HTTP/1.1 and chunked transfer encoding wouldn't be that useful\n> +on the Internet today, since it would break lots of traffic.\n> ++\n> +Note that increasing this value will increase the memory used on every relevant\n> +push that Git does over HTTP or HTTPS, since the entire buffer is allocated\n> +regardless of whether or not it is all used.  Thus, it's best to leave it at the\n> +default unless you are sure you need a different value.\n> +\n> +[[configure-editor]]\n> +How do I configure a different editor?::\n> +\tIf you haven't specified an editor specifically for Git, it will by default\n> +\tuse the editor you've configured using the `VISUAL` or `EDITOR` environment\n> +\tvariables, or if neither is specified, the system default (which is usually\n> +\t`vi`).  Since some people find `vi` difficult to use, it may be desirable to\n> +\tchange the editor used.\n> ++\n> +If you want to configure a general editor for most programs which need one, you\n> +can edit your shell configuration (e.g., `~/.bashrc` or `~/.zshenv`) to contain\n> +a line setting the `EDITOR` or `VISUAL` environment variable to an appropriate\n> +value.  For example, if you preferred the editor `nano`, then you could write\n> +the following:\n> ++\n> +----\n> +export VISUAL=nano\n> +----\n\nI'll swallow my pride as a Vim user here and say that I think 'nano' is\na good choice to reference directly here; it seems to fit right into the\nexperience level this particular Q is targeting. Nice.\n\n> ++\n> +If you want to configure an editor specifically for Git, you can either set the\n> +`core.editor` configuration value or the `GIT_EDITOR` environment variable.  You\n> +can see linkgit:git-var[1] for details on the order in which these options are\n> +consulted.\n> ++\n> +Note that in all cases, the editor value will be passed to the shell, so any\n> +arguments containing spaces should be appropriately quoted.  Additionally, if\n> +your editor normally detaches from the terminal when invoked, you should specify\n> +it with an argument that makes it not do that, or else Git will not see any\n> +changes.  An example of a configuration addressing both of these issues on\n> +Windows would be the configuration `\"C:\\Program Files\\Vim\\gvim.exe\" --nofork`,\n> +which quotes the filename with spaces and specifies the `--nofork` option to\n> +avoid backgrounding the process.\n> +\n> +Credentials\n> +-----------\n> +\n> +[[http-credentials]]\n> +How do I specify my credentials when pushing over HTTP?::\n> +\tThe easiest way to do this is to use a credential helper via the\n> +\t`credential.helper` configuration.  Most systems provide a standard choice to\n> +\tintegrate with the system credential manager.  For example, Git for Windows\n> +\tprovides the `wincred` credential manager, macOS has the `osxkeychain`\n> +\tcredential manager, and Unix systems with a standard desktop environment can\n> +\tuse the `libsecret` credential manager.  All of these store credentials in an\n> +\tencrypted store to keep your passwords or tokens secure.\n> ++\n> +In addition, you can use the `store` credential manager which stores in a file\n> +in your home directory, or the `cache` credential manager, which does not\n> +permanently store your credentials, but does prevent you from being prompted for\n> +them for a certain period of time.\n> ++\n> +You can also just enter your password when prompted, or you can place the\n> +password (which must be percent-encoded) in the URL.  The latter option is not\n> +particularly secure and can lead to accidental exposure of credentials, so it is\n> +not recommended.\n> +\n> +[[http-credentials-environment]]\n> +How do I read a password or token from an environment variable?::\n> +  The `credential.helper` configuration option can also take an arbitrary shell\n> +\tcommand that produces the credential protocol on standard output.  This is\n> +\tuseful when passing credentials into a container, for example.\n> ++\n> +Such a shell command can be specified by starting the option value with an\n> +exclamation point.  If your password or token were stored in the `GIT_TOKEN`,\n> +you could run the following command to set your credential helper:\n> ++\n> +----\n> +$ git config credential.helper \\\n> +\t'!f() { echo username=author; echo \"password=$GIT_TOKEN\"; };f'\n> +----\n> +\n> +[[http-reset-credentials]]\n> +How do I change the password or token I've saved in my credential manager?::\n> +\tUsually, if the password or token is invalid, Git will erase it and prompt for\n> +\ta new one.  However, there are times when this doesn't always happen.  To\n> +\tchange the password or token, you can erase the existing credentials and then\n> +\tGit will prompt for new ones.  To erase credentials, use a syntax like the\n> +\tfollowing (substituting your username and the hostname):\n> ++\n> +----\n> +$ echo url=https://author@git.example.org | git credential reject\n> +----\n> +\n> +[[multiple-accounts-http]]\n> +How do I use multiple accounts with the same hosting provider using HTTP?::\n> +  Usually the easiest way to distinguish between these accounts is to use the\n> +\tusername in the URL.  For example, if you have the accounts `author` and\n> +\t`committer` on `git.example.org`, you can use the URLs\n> +\thttps://author@git.example.org/org1/project1.git and\n> +\thttps://committer@git.example.org/org2/project2.git.  This way, when you use a\n> +\tcredential helper, it will automatically try to look up the correct\n> +\tcredentials for your account.  If you already have a remote set up, you can\n> +\tchange the URL with something like `git remote set-url origin\n> +\thttps://author@git.example.org/org1/project1.git` (see linkgit:git-remote[1]\n> +\tfor details).\n> +\n> +[[multiple-accounts-ssh]]\n> +How do I use multiple accounts with the same hosting provider using SSH?::\n> +\tWith most hosting providers that support SSH, a single key pair uniquely\n> +\tidentifies a user.  Therefore, to use multiple accounts, it's necessary to\n> +\tcreate a key pair for each account.  If you're using a reasonably modern\n> +\tOpenSSH version, you can create a new key pair with something like `ssh-keygen\n> +\t-t ed25519 -f ~/.ssh/id_committer`.  You can then register the public key (in\n> +\tthis case, `~/.ssh/id_committer.pub`; note the `.pub`) with the hosting\n> +\tprovider.\n> ++\n> +Most hosting providers use a single SSH account for pushing; that is, all users\n> +push to the `git` account (e.g., `git@git.example.org`).  If that's the case for\n> +your provider, you can set up multiple aliases in SSH to make it clear which key\n> +pair to use.  For example, you could write something like the following,\n> +substituting the proper private key file:\n> ++\n> +----\n> +# This is the account for author on git.example.org.\n> +Host example_author\n> +   HostName git.example.org\n> +\t User git\n> +\t # This is the key pair registered for author with git.example.org.\n> +\t IdentityFile ~/.ssh/id_author\n> +\t IdentitiesOnly yes\n> +# This is the committer for author on git.example.org.\n> +Host example_committer\n> +   HostName git.example.org\n> +\t User git\n> +\t # This is the key pair registered for committer with git.example.org.\n> +\t IdentityFile ~/.ssh/id_committer\n> +\t IdentitiesOnly yes\n> +----\n> ++\n> +Then, you can adjust your push URL to use `git@example_author` or\n> +`git@example_committer` instead of `git@example.org` (e.g., `git remote set-url\n> +git@example_author:org1/project1.git`).\n> +\n> +Common Issues\n> +-------------\n> +\n> +[[last-commit-amend]]\n> +I've made a mistake in the last commit.  How do I change it?::\n> +\tYou can make the appropriate change to your working tree, run `git add <file>`\n> +\tto stage it, and then `git commit --amend`.  Your change will be included in\n> +\tthe commit, and you'll be prompted to edit the commit message again; if you\n> +\tdon't want to edit it, you can use the `--no-edit` option to `git commit` in\n> +\taddition, or just save and quit when your editor opens.\n> +\n> +[[undo-previous-change]]\n> +I've made a change with a bug and it's been included in the main branch.  How should I undo it?::\n> +\tThe usual way to deal with this is to use `git revert`.  This preserves the\n> +\thistory that the original change was made and was a valuable contribution, but\n> +\talso introduces a new commit that undoes those changes because the original\n> +\thad a problem.  The commit message of the revert indicates the commit which\n> +\twas reverted and can be edited to include an explanation as to why the revert\n> +\twas made.\n> +\n> +[[ignore-tracked-files]]\n> +How do I ignore changes to a tracked file?::\n> +  Git doesn't provide a way to do this.  The reason is that if Git needs to\n> +\toverwrite this file, such as during a checkout, it doesn't know whether the\n> +\tchanges to the file are precious and should be kept, or whether they are\n> +\tirrelevant and can safely be destroyed.  Therefore, it has to take the safe\n> +\troute and always preserve them.\n> ++\n> +Some people are tempted to use certain features of `git update-index`, namely\n> +the assume-unchanged and skip-worktree bits, but these don't work properly for\n> +this purpose and shouldn't be used this way.\n\nNot really on topic for this particular paragraph, but there are a lot\nof instances of \"Some people ...\" - in general, would it be less\ncombative to say something like \"It's tempting to...\" or \"It might seem\nlike a good idea to...\"? That way it feels less like \"there are people\nwho do X and they are wrong\" and more like \"X might seem like a good\nidea but it isn't\". Or to put it another way, let's attack the bad idea,\nnot the people who suggest it.\n\n> ++\n> +If your goal is to modify a configuration file, it can often be helpful to have\n> +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> +Hooks\n> +-----\n> +\n> +[[restrict-with-hooks]]\n> +How do I prevent users from making certain changes with hooks?::\n> +\tThe only safe place to make these changes is on the remote repository (i.e.,\n> +\tthe Git server), usually in the `pre-receive` hook or in a continuous\n> +\tintegration (CI) system.  These are the locations in which policy can be\n> +\tenforced effectively.\n> ++\n> +Some people try to use `pre-commit` hooks (or, for commit messages, `commit-msg`\n> +hooks) to check these things, which is fine if you're working as a solo\n> +developer and want the tooling to help you.  However, using hooks on a developer\n> +machine is not effective as a policy control because a user can bypass these\n> +hooks with `--no-verify` without being noticed (among various other ways).  Git\n> +assumes that the user is in control of their local repositories and doesn't try\n> +to prevent this or tattle on the user.\n> ++\n> +In addition, some advanced users find `pre-commit` hooks to be an impediment to\n> +workflows that use temporary commits to stage work in progress or that create\n> +fixup commits, so it's better to push these kinds of checks to the server\n> +anyway.\n> +\n> +Cross-Platform Issues\n> +~~~~~~~~~~~~~~~~~~~~~\n> +\n> +[[windows-text-binary]]\n> +I'm on Windows and my text files are detected as binary.::\n> +\tGit works best when you store text files as UTF-8.  Many programs on Windows\n> +\tsupport UTF-8, but some do not and only use the little-endian UTF-16 format,\n> +\twhich Git detects as binary.  If you can't use UTF-8 with your programs, you\n> +\tcan specify a working tree encoding that indicates which encoding your files\n> +\tshould be checked out with, while still storing these files as UTF-8 in the\n> +\trepository.  This allows tools like linkgit:git-diff[1] to work as expected,\n> +\twhile still allowing your tools to work.\n> ++\n> +To do so, you can specify a linkgit:gitattributes[5] pattern with with the\n> +`working-tree-encoding` attribute.  For example, the following pattern sets all\n> +C files to use UTF-16LE-BOM, which is a common encoding on Windows:\n> ++\n> +----\n> +*.c\tworking-tree-encoding=UTF-16LE-BOM\n> +----\n> ++\n> +You will need to run `git add --renormalize` to have this take effect.  Note\n> +that if you are making these changes on a project that is used across platforms,\n> +you'll probably want to make it in a per-user configuration file or in the one\n> +in `$GIT_DIR/info/attributes`, since making it in a `.gitattributes` file in\n> +the repository will apply to all users of the repository.\n> ++\n> +See the following entry for information about normalizing line endings as well,\n> +and see linkgit:gitattributes[5] for more information about attribute files.\n> +\n> +[[windows-diff-control-m]]\n> +I'm on Windows and git diff shows my files as having a `^M` at the end.::\n> +\tBy default, Git expects files to be stored with Unix line endings.  As such,\n> +\tthe carriage return (`^M`) that is part of a Windows line ending results is\n> +\tshow because it is considered to be trailing whitespace.  Git defaults to\n> +\tshowing trailing whitespace only on new lines, not existing ones.\n> ++\n> +You can store the files in the repository with Unix line endings and convert\n> +them automatically to your platform's line endings.  To do that, set the\n> +configuration option `core.eol` to `native` and see the following entry for\n> +information about how to configure files as text or binary.\n> ++\n> +You can also control this behavior with the `core.whitespace` setting if you\n> +don't wish to remove the carriage returns from your line endings.\n> +\n> +[[recommended-storage-settings]]\n> +What's the recommended way to store files in Git?::\n> +\tWhile Git can store and handle any file of any type, there are some settings\n> +\tthat work better than others.  In general, we recommend that text files be\n> +\tstored in UTF-8 without a byte-order mark (BOM) with LF (Unix-style) endings.\n> +\tWe also recommend the use of UTF-8 (again, without BOM) in commit messages.\n> +\tThese are the settings that work best across platforms and with tools such as\n> +\t`git diff` and `git merge`.\n> ++\n> +Additionally, if you have a choice between storage formats that are text based\n> +or non-text based, we recommend storing files in the text format and, if\n> +necessary, transforming them into the other format.  For example, a text-based\n> +SQL dump with one record per line will work much better for diffing and merging\n> +than an actual database file.  Similarly, text-based formats such as Markdown\n> +and AsciiDoc will work better than binary formats such as Microsoft Word and\n> +PDF.\n> ++\n> +Similarly, storing binary dependencies (e.g., shared libraries or JAR files) or\n> +build products in the repository is generally not recommended.  Dependencies and\n> +build products are best stored on an artifact or package server with only\n> +references, URLs, and hashes stored in the repository.\n> ++\n> +We also recommend setting a link:gitattributes[5] file to explicitly mark which\n> +files are text and which are binary.  If you want Git to guess, you can set the\n> +attribute `text=auto`.  For example, the following might be appropriate in some\n> +projects:\n> ++\n> +----\n> +# By default, guess.\n> +*\t\t\ttext=auto\n> +# Mark all C files as text.\n> +*.c\t\ttext\n> +# Mark all JPEG files as binary.\n> +*.jpg\tbinary\n> +----\n> ++\n> +These settings help tools pick the right format for output such as patches and\n> +result in files being checked out in the appropriate line ending for the\n> +platform.\n> +\n> +GIT\n> +---\n> +Part of the linkgit:git[1] suite\n"},{"id":"393429","messageId":"xmqqo8stdx43.fsf@gitster.c.googlers.com","threadId":"53000","inReplyTo":"20200318230030.GA45325@google.com","subject":"Re: [PATCH 1/1] docs: add a FAQ","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-03-19T00:09:00Z","receivedAt":"2020-03-19T00:09:08Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Emily Shaffer <emilyshaffer@google.com> writes:\n\n> Not really on topic for this particular paragraph, but there are a lot\n> of instances of \"Some people ...\" - in general, would it be less\n> combative to say something like \"It's tempting to...\" or \"It might seem\n> like a good idea to...\"? That way it feels less like \"there are people\n> who do X and they are wrong\" and more like \"X might seem like a good\n> idea but it isn't\". Or to put it another way, let's attack the bad idea,\n> not the people who suggest it.\n\nThanks for a perspective; I personally did not find that \"Some\npeople do X\" accuses them of doing it wrong, but you certainly\nhave a point.\n"},{"id":"393473","messageId":"20200319170204.5291-1-shouryashukla.oo@gmail.com","threadId":"53000","inReplyTo":"20200315223923.170371-2-sandals@crustytoothpaste.net","subject":"Re: [PATCH 1/1] docs: add a FAQ","fromName":"Shourya Shukla","fromEmail":"shouryashukla.oo@gmail.com","sentAt":"2020-03-19T17:02:04Z","receivedAt":"2020-03-19T17:02:18Z","isPatch":true,"sender":{"key":"shouryashukla.oo@gmail.com","avatar":"https://avatars.githubusercontent.com/u/43680618?v=4"},"body":"This seems like a really good idea! There are tons of redundant questions on StackOverflow\nregarding Git in fact. One thing I want to ask, is that will this FAQ cover questions of the type:\n\n\"How do I change the remote of my repository?\"\n\"What is the difference between a git merge and a git pull?\"\n\"Git is tracking the files mentioned in .gitignore, what to do?\"\n\"When do I rebase and when do I merge?\"\n\nAnd stuff like that. Basically questions which are more of a help to someone. Or are we focusing\nonly on the FAQs to kind of guide the user in Git, aiming to answer the fundamental questions and\nnot the general problems faced by a user?\n\nAlso, I had some FAQs in mind, can I add some into this?\n\nI really appreciate your initiative! :)\n\nRegards,\nShourya Shukla\n"},{"id":"393495","messageId":"20200319233138.GE366567@camp.crustytoothpaste.net","threadId":"53000","inReplyTo":"20200319170204.5291-1-shouryashukla.oo@gmail.com","subject":"Re: [PATCH 1/1] docs: add a FAQ","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2020-03-19T23:31:38Z","receivedAt":"2020-03-19T23:31:48Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2020-03-19 at 17:02:04, Shourya Shukla wrote:\n> This seems like a really good idea! There are tons of redundant questions on StackOverflow\n> regarding Git in fact. One thing I want to ask, is that will this FAQ cover questions of the type:\n> \n> \"How do I change the remote of my repository?\"\n> \"What is the difference between a git merge and a git pull?\"\n> \"Git is tracking the files mentioned in .gitignore, what to do?\"\n> \"When do I rebase and when do I merge?\"\n> \n> And stuff like that. Basically questions which are more of a help to someone. Or are we focusing\n> only on the FAQs to kind of guide the user in Git, aiming to answer the fundamental questions and\n> not the general problems faced by a user?\n\nI think these kinds of questions are good things to add.  I do see the\ntracked-file-in-.gitignore question a lot in particular.\n\nPart of my goal here is to address these kinds of questions in Git's\ndocumentation itself.  If many people are asking the same question on\nStack Overflow, clearly there's confusion and we should address that by\nmaking our documentation clearer and easier to find.\n\nMy hope is that folks will start linking to the FAQ once we have it up\non the website and it will become a good starting point for people to\nfind answers when they're unsure of something.\n\n> Also, I had some FAQs in mind, can I add some into this?\n\nI had always planned this patch as a start.  I fully expect that we'll\nadd more to it in the future, so I'd love to see additional\ncontributions.\n-- \nbrian m. carlson: Houston, Texas, US\nOpenPGP: https://keybase.io/bk2204\n"},{"id":"393498","messageId":"20200319234934.GF366567@camp.crustytoothpaste.net","threadId":"53000","inReplyTo":"20200318230030.GA45325@google.com","subject":"Re: [PATCH 1/1] docs: add a FAQ","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2020-03-19T23:49:34Z","receivedAt":"2020-03-19T23:49:42Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2020-03-18 at 23:00:30, Emily Shaffer wrote:\n> On Sun, Mar 15, 2020 at 10:39:23PM +0000, brian m. carlson wrote:\n> > Git is an enormously flexible and powerful piece of software.  However,\n> > it can be intimidating for many users and there are a set of common\n> > questions that users often ask.  While we already have some new user\n> > documentation, it's worth adding a FAQ to address common questions that\n> > users often have.  Even though some of this is addressed elsewhere in\n> > the documentation, experience has shown that it is difficult for users\n> > to find, so a centralized location is helpful.\n> \n> It's true that some of it is duplicated; if we're worried about the info\n> getting out of sync, we might be able to do something like\n> Documentation/config so we're pulling in a single piece of text to both\n> places.\n\nI'm not worried about this, since most of it has been this way for a\nlong time.\n\n> > +[[user-name]]\n> > +What should I put in `user.name`?::\n> > +  You should put your personal name; that is, the name that other humans call\n> > +\tyou.  This will be the name portion that is stored in every commit you make.\n> \n> I like the direction but I think it is still a little unclear. Other\n> humans call me Emily, but I want to put \"Emily Shaffer\" in my user.name.\n> I wonder how we can suggest full name in a way that's as universal as\n> \"the name that other humans call you\"? I think I got around to this\n> point by using examples when covering the SOB in MyFirstContribution, so\n> I don't have a good answer off the top of my head.\n\nYeah, this is tricky, since in many contexts the phrase \"full name\"\nimplies using the entirety of every part of your name, and most people\nwith middle names don't put them in the \"user.name\" entry.  Yet we want\nit to be appropriate for people across a wide variety of cultures.\n\nMaybe we should say something like this:\n\n  You should put your personal name, generally a form using a given name\n  and family name.  This will be the name portion that is stored in\n  every commit you make.\n\nMany cultures have a given name and a family name of some sort.  If we\nwanted to provide an example, we could use Junio:\n\n  For example, the current maintainer of Git uses \"Junio C Hamano\".\n\n> > +[[http-postbuffer]]\n> > +What does `http.postBuffer` really do?::\n> > +\tThis option changes the size of the buffer that Git uses when pushing data to\n> > +\ta remote over HTTP or HTTPS.  If the data is larger than this size, libcurl,\n> > +\twhich handles the HTTP support for Git, will use chunked transfer encoding\n> > +\tsince it isn't known ahead of time what the size of the pushed data will be.\n> > ++\n> > +Leaving this value at the default size is fine unless you know that either the\n> > +remote server or a proxy in the middle doesn't support HTTP/1.1 (which\n> > +introduced the chunked transfer encoding) or is known to be broken with chunked\n> > +data.  People often suggest this as a solution for generic push problems, but\n> > +since almost every server and proxy supports at least HTTP/1.1, raising this\n> > +value usually doesn't solve most push problems.  A server or proxy that didn't\n> \n> This might be burying the lede a little for someone frantically skimming\n> for an answer. If I was really spinning my wheels I might read \"People\n> often suggest this as a solution for generic push problems\" and go try\n> it. Is \"People often (erroneously) suggest this ...\" too verbose?\n\nNo, I think that's a good answer.\n\n> > +If you want to configure a general editor for most programs which need one, you\n> > +can edit your shell configuration (e.g., `~/.bashrc` or `~/.zshenv`) to contain\n> > +a line setting the `EDITOR` or `VISUAL` environment variable to an appropriate\n> > +value.  For example, if you preferred the editor `nano`, then you could write\n> > +the following:\n> > ++\n> > +----\n> > +export VISUAL=nano\n> > +----\n> \n> I'll swallow my pride as a Vim user here and say that I think 'nano' is\n> a good choice to reference directly here; it seems to fit right into the\n> experience level this particular Q is targeting. Nice.\n\nI'm also a Vim user, but I took this idea from Debian, which uses the\noptions nano, nano-tiny, and vi (in that order) for its sensible-editor\nutility if the user hasn't specified an editor any other way.  In any\nevent, the user can extrapolate from the example if nano isn't to their\ntastes.\n\n> > +[[ignore-tracked-files]]\n> > +How do I ignore changes to a tracked file?::\n> > +  Git doesn't provide a way to do this.  The reason is that if Git needs to\n> > +\toverwrite this file, such as during a checkout, it doesn't know whether the\n> > +\tchanges to the file are precious and should be kept, or whether they are\n> > +\tirrelevant and can safely be destroyed.  Therefore, it has to take the safe\n> > +\troute and always preserve them.\n> > ++\n> > +Some people are tempted to use certain features of `git update-index`, namely\n> > +the assume-unchanged and skip-worktree bits, but these don't work properly for\n> > +this purpose and shouldn't be used this way.\n> \n> Not really on topic for this particular paragraph, but there are a lot\n> of instances of \"Some people ...\" - in general, would it be less\n> combative to say something like \"It's tempting to...\" or \"It might seem\n> like a good idea to...\"? That way it feels less like \"there are people\n> who do X and they are wrong\" and more like \"X might seem like a good\n> idea but it isn't\". Or to put it another way, let's attack the bad idea,\n> not the people who suggest it.\n\nSure, I think that's a good idea.  Thanks for the suggestion.\n-- \nbrian m. carlson: Houston, Texas, US\nOpenPGP: https://keybase.io/bk2204\n"}]}