git/Documentation/gitfaq.txt, branch v2.46.2

gitfaq: add entry about syncing working trees

2024-07-10T04:24:42Z

Users very commonly want to sync their working tree with uncommitted changes across machines, often to carry across in-progress work or stashes. Despite this not being a recommended approach, users want to do it and are not dissuaded by suggestions not to, so let's recommend a sensible technique. The technique that many users are using is their preferred cloud syncing service, which is a bad idea. Users have reported problems where they end up with duplicate files that won't go away (with names like "file.c 2"), broken references, oddly named references that have date stamps appended to them, missing objects, and general corruption and data loss. That's because almost all of these tools sync file by file, which is a great technique if your project is a single word processing document or spreadsheet, but is utterly abysmal for Git repositories because they don't necessarily snapshot the entire repository correctly. They also tend to sync the files immediately instead of when the repository is quiescent, so writing multiple files, as occurs during a commit or a gc, can confuse the tools and lead to corruption. We know that the old standby, rsync, is up to the task, provided that the repository is quiescent, so let's suggest that and dissuade people from using cloud syncing tools. Let's tell people about common things they should be aware of before doing this and that this is still potentially risky. Additionally, let's tell people that Git's security model does not permit sharing working trees across users in case they planned to do that. While we'd still prefer users didn't try to do this, hopefully this will lead them in a safer direction. Signed-off-by: brian m. carlson Signed-off-by: Junio C Hamano

gitfaq: give advice on using eol attribute in gitattributes

2024-07-10T04:24:42Z

In the FAQ, we tell people how to use the text attribute, but we fail to explain what to do with the eol attribute. As we ourselves have noticed, most shell implementations do not care for carriage returns, and as such, people will practically always want them to use LF endings. Similar things can be said for batch files on Windows, except with CRLF endings. Since these are common things to have in a repository, let's help users make a good decision by recommending that they use the gitattributes file to correctly check out the endings. In addition, let's correct the cross-reference to this question, which originally referred to "the following entry", even though a new entry has been inserted in between. The cross-reference notation should prevent this from occurring and provide a link in formats, such as HTML, which support that. Signed-off-by: brian m. carlson Signed-off-by: Junio C Hamano

gitfaq: add documentation on proxies

2024-07-10T04:24:42Z

Many corporate environments and local systems have proxies in use. Note the situations in which proxies can be used and how to configure them. At the same time, note what standards a proxy must follow to work with Git. Explicitly call out certain classes that are known to routinely have problems reported various places online, including in the Git for Windows issue tracker and on Stack Overflow, and recommend against the use of such software, noting that they are associated with myriad security problems (including, for example, breaking sandboxing and image integrity[0], and, for TLS middleboxes, the use of insecure protocols and ciphers and lack of certificate verification[1]). Don't mention the specific nature of these security problems in the FAQ entry because they are extremely numerous and varied and we wish to keep the FAQ entry relatively brief. [0] https://issues.chromium.org/issues/40285192 [1] https://faculty.cc.gatech.edu/~mbailey/publications/ndss17_interception.pdf Signed-off-by: brian m. carlson Signed-off-by: Junio C Hamano

Update docs for change of default merge backend

2021-08-05T22:35:02Z

Make it clear that `ort` is the default merge strategy now rather than `recursive`, including moving `ort` to the front of the list of merge strategies. Signed-off-by: Elijah Newren Signed-off-by: Junio C Hamano

docs: explain how to deal with files that are always modified

2020-09-21T04:29:02Z

Users frequently have problems where two filenames differ only in case, causing one of those files to show up consistently as being modified. Let's add a FAQ entry that explains how to deal with that. In addition, let's explain another common case where files are consistently modified, which is when files using a smudge or clean filter have not been run through that filter. Explain the way to fix this as well. Signed-off-by: brian m. carlson Signed-off-by: Junio C Hamano

docs: explain why reverts are not always applied on merge

2020-09-21T04:29:02Z

A common scenario is for a user to apply a change to one branch and cherry-pick it into another, then later revert it in the first branch. This results in the change being present when the two branches are merged, which is confusing to many users. We already have documentation for how this works in `git merge`, but it is clear from the frequency with which this is asked that it's hard to grasp. We also don't explain to users that they are better off doing a rebase in this case, which will do what they intended. Let's add an entry to the FAQ telling users what's happening and advising them to use rebase here. Signed-off-by: brian m. carlson Signed-off-by: Junio C Hamano

docs: explain why squash merges are broken with long-running branches

2020-09-21T04:29:02Z

In many projects, squash merges are commonly used, primarily to keep a tidy history in the face of developers who do not use logically independent, bisectable commits. As common as this is, this tends to cause significant problems when squash merges are used to merge long-running branches due to the lack of any new merge bases. Even very experienced developers may make this mistake, so let's add a FAQ entry explaining why this is problematic and explaining that regular merge commits should be used to merge two long-running branches. Signed-off-by: brian m. carlson Signed-off-by: Junio C Hamano

Merge branch 'ss/faq-ignore'

2020-05-26T16:32:08Z

Doc markup fix. * ss/faq-ignore: gitfaq: avoid validation error with older asciidoc

gitfaq: avoid validation error with older asciidoc

2020-05-25T18:59:26Z

When building with asciidoc-8.4.5 (as found on CentOS/Red Hat 6), the period in the "[[files-in-.gitignore-are-tracked]]" anchor is not properly parsed as a section: WARNING: gitfaq.txt: line 245: missing [[files-in-.gitignore-are-tracked]] section The resulting XML file fails to validate with xmlto: xmlto: /git/Documentation/gitfaq.xml does not validate (status 3) xmlto: Fix document syntax or use --skip-validation option /git/Documentation/gitfaq.xml:3: element refentry: validity error : Element refentry content does not follow the DTD, expecting (beginpage? , indexterm* , refentryinfo? , refmeta? , (remark | link | olink | ulink)* , refnamediv+ , refsynopsisdiv? , (refsect1+ | refsection+)), got (refmeta refnamediv refsynopsisdiv refsect1 refsect1 refsect1 refsect1 variablelist refsect1 refsect1 ) Document /git/Documentation/gitfaq.xml does not validate Let's avoid breaking users of platforms which ship an old version of asciidoc, since the cost to do so is quite low. Reported-by: Son Luong Ngoc Signed-off-by: Todd Zullinger Signed-off-by: Junio C Hamano

Merge branch 'ss/faq-fetch-pull'

2020-05-13T19:19:19Z

Random bits of FAQ. * ss/faq-fetch-pull: gitfaq: fetching and pulling a repository