From patchwork Tue Jul 9 23:37:43 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "brian m. carlson" X-Patchwork-Id: 13728628 Received: from complex.crustytoothpaste.net (complex.crustytoothpaste.net [172.105.7.114]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id B9E50189F53 for ; Tue, 9 Jul 2024 23:38:54 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=172.105.7.114 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1720568336; cv=none; b=u92h4kNkmRdRLRwgTqj1p4Yy1SefvRp6zNBMr2tDMytdQEzbPLgc1bWvnskhqA6xqExvBWpNhNXMHNsL8V279M55oZKPwelcNOGxo50MgnGns1dNfOJur7lKboEVcSfSjS53yxzFI8G6yd3wpP0OCV9YddKGcsWzfdrj7EXx5L0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1720568336; c=relaxed/simple; bh=B8m4f5yFWS/y869OG/dDnD5pF0tJnXz+lxQAnaC3FDU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=L5kv/8Ber8gUIWJhCqXw7cCXWakr0h7N7+DFRdvvsiTRiDqz6OgdY29DpBPPN6Zmmj9k7x0WpluUnLia2Yvq9pYY3JqpWVewJFJ4AJB7qVchLPP/W041tY3JG0UEYPB2W+EmIXl8dJLglzuoyg0RqQu2vGj5dmEuqnhDV4ox/bw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=crustytoothpaste.net; spf=pass smtp.mailfrom=crustytoothpaste.net; dkim=pass (3072-bit key) header.d=crustytoothpaste.net header.i=@crustytoothpaste.net header.b=a9uCNbxw; arc=none smtp.client-ip=172.105.7.114 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=crustytoothpaste.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=crustytoothpaste.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (3072-bit key) header.d=crustytoothpaste.net header.i=@crustytoothpaste.net header.b="a9uCNbxw" DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=crustytoothpaste.net; s=default; t=1720568333; bh=B8m4f5yFWS/y869OG/dDnD5pF0tJnXz+lxQAnaC3FDU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From:Reply-To: Subject:Date:To:CC:Resent-Date:Resent-From:Resent-To:Resent-Cc: In-Reply-To:References:Content-Type:Content-Disposition; b=a9uCNbxws1h8GW8jcp4OuQN0rwdibsDR7O4r4X5gekmDTkGNftGoAvCv4Atv9ye/r Dv7heLsh30DskhWXhIREqkU+yTA8xQQdAbydpH0gjHxZrMbshBMDRgQbVh4+gpZlDl v6XDk7LMdgkhvW8PRv4+H3BoWpioj4iweLHwx34Denjon/s0sd9jJ9bz4deWgcHNrt 3IuHZlvWu/ZBKs8UgmZllQyhTQSm9GIFwwBV96pJeic+O1OFP+dyUt9wo0IagJ39Fp mV7N2xyhNSD8qQTAJxilUhhcfzGYwCw6Ry8RXBk9UzV1/jv2+6ANU+i5FO9X0jA2gY 8tu8oMqJy2pxnuf5f566hVsILIZ8ifJbx+WSd/FtA+WOIApL/ljrYgceQlnub6lw1V 1zoHMQK0Ha3aGH7JQE2vN4JGJJh6V3Uihu86LXVzmZFBKHp8NZKdAPVTt3BwsftWhR H6bzO932PlGH7Wg1EdmmZMzn1YnW21ld4F71d/nCXGa7aejRZcD Received: from tapette.crustytoothpaste.net (unknown [IPv6:2001:470:b056:101:e59a:3ed0:5f5c:31f3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (prime256v1) server-digest SHA256) (No client certificate requested) by complex.crustytoothpaste.net (Postfix) with ESMTPSA id D41A6209A8; Tue, 9 Jul 2024 23:38:53 +0000 (UTC) From: "brian m. carlson" To: Cc: Junio C Hamano , Johannes Schindelin , Eric Sunshine , Derrick Stolee , Jeff King Subject: [PATCH v4 1/4] gitfaq: add documentation on proxies Date: Tue, 9 Jul 2024 23:37:43 +0000 Message-ID: <20240709233746.445860-2-sandals@crustytoothpaste.net> X-Mailer: git-send-email 2.45.2.753.g447d99e1c3b In-Reply-To: <20240709233746.445860-1-sandals@crustytoothpaste.net> References: <20240704003818.750223-1-sandals@crustytoothpaste.net> <20240709233746.445860-1-sandals@crustytoothpaste.net> Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 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 --- Documentation/gitfaq.txt | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt index 8c1f2d5675..e4125b1178 100644 --- a/Documentation/gitfaq.txt +++ b/Documentation/gitfaq.txt @@ -241,6 +241,42 @@ How do I know if I want to do a fetch or a pull?:: ignore the upstream changes. A pull consists of a fetch followed immediately by either a merge or rebase. See linkgit:git-pull[1]. +[[proxy]] +Can I use a proxy with Git?:: + Yes, Git supports the use of proxies. Git honors the standard `http_proxy`, + `https_proxy`, and `no_proxy` environment variables commonly used on Unix, and + it also can be configured with `http.proxy` and similar options for HTTPS (see + linkgit:git-config[1]). The `http.proxy` and related options can be + customized on a per-URL pattern basis. In addition, Git can in theory + function normally with transparent proxies that exist on the network. ++ +For SSH, Git can support a proxy using OpenSSH's `ProxyCommand`. Commonly used +tools include `netcat` and `socat`. However, they must be configured not to +exit when seeing EOF on standard input, which usually means that `netcat` will +require `-q` and `socat` will require a timeout with something like `-t 10`. +This is required because the way the Git SSH server knows that no more requests +will be made is an EOF on standard input, but when that happens, the server may +not have yet processed the final request, so dropping the connection at that +point would interrupt that request. ++ +An example configuration entry in `~/.ssh/config` with an HTTP proxy might look +like this: ++ +---- +Host git.example.org + User git + ProxyCommand socat -t 10 - PROXY:proxy.example.org:%h:%p,proxyport=8080 +---- ++ +Note that in all cases, for Git to work properly, the proxy must be completely +transparent. The proxy cannot modify, tamper with, or buffer the connection in +any way, or Git will almost certainly fail to work. Note that many proxies, +including many TLS middleboxes, Windows antivirus and firewall programs other +than Windows Defender and Windows Firewall, and filtering proxies fail to meet +this standard, and as a result end up breaking Git. Because of the many +reports of problems and their poor security history, we recommend against the +use of these classes of software and devices. + Merging and Rebasing -------------------- From patchwork Tue Jul 9 23:37:44 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "brian m. carlson" X-Patchwork-Id: 13728631 Received: from complex.crustytoothpaste.net (complex.crustytoothpaste.net [172.105.7.114]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id BDD50189F55 for ; Tue, 9 Jul 2024 23:38:54 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=172.105.7.114 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1720568337; cv=none; b=FkPqwsiuIqcI4bSrf/7JrQzaH2Mrc6hp28cVocK9MHLm6C8wg5SH5cGAxZL8ogXZ+q5KbUGJR4OV4eth0zPwvrT1Lwz9fm4BjilTdwLZfqkXoXwcbtpT1x9li8U4wYRsfXKiwI0P3ew7Dtc/J3ZZhg5bFng/QWChd2L0HzRJizE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1720568337; c=relaxed/simple; bh=vNMbBFnoScgKbEkoOuaMFqQOoUP0kPL/tSTkcH64rvA=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=r77rPNbBAaQhiDkpPuOK1Gf62wz0bwhhPEje059PHP9IrmdSNGncXU3+LFtaJKsQ2elfE9dllZaoreAlgI4ML6xePfV6Yt+msimixH6XlPgnmUZ9fK5Sul4AAENJRCVtggOKvAsFcqBAJNlcu6vm/z2cWkkaP/XXhTLCn7OuGZk= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=crustytoothpaste.net; spf=pass smtp.mailfrom=crustytoothpaste.net; dkim=pass (3072-bit key) header.d=crustytoothpaste.net header.i=@crustytoothpaste.net header.b=yxBOrprh; arc=none smtp.client-ip=172.105.7.114 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=crustytoothpaste.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=crustytoothpaste.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (3072-bit key) header.d=crustytoothpaste.net header.i=@crustytoothpaste.net header.b="yxBOrprh" DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=crustytoothpaste.net; s=default; t=1720568333; bh=vNMbBFnoScgKbEkoOuaMFqQOoUP0kPL/tSTkcH64rvA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From:Reply-To: Subject:Date:To:CC:Resent-Date:Resent-From:Resent-To:Resent-Cc: In-Reply-To:References:Content-Type:Content-Disposition; b=yxBOrprhWNP7S64cJiX7Fjp07B5DN4Ym09rjKZWCV5bd7zQlYIZPx92Gqfd72m8N0 OhMF3YS7mOUGPQ7oQPEZSwNmFk4aJM1TbFrt4Ufpw+fi7oeE9uYXwpUupFa/homVtG 9SCJHrav3LznbvZD/brubLCjIcRog+srC1Hzcl8OND92jDIy7tSs4ec4bPT0fwfw8q PCRzDrHBsd5GvBj0G8R6KP3VksxbwwImz4GEc60VH+BM0ECJ5x4o1TItSa5YBwWOC4 1ZG8q9kV6opDK7RTIBP4xghdWfSrXq/4TzNgPymm0hS0AO3Fwi+BbL/HIW4jvf6E3n cgWdy3WAn4WOJRYHwYOMyArUKfp/lCLU5PwRck11EzOeWniyu5GGxIa8QBvwOonu3v 05AgRNZrbdx27TTnWfJjIaVA0JjpT6eZ3/9KoD+9uwErILnRhhh4Vje1iXjQGDTaZA lQ1SchTeuSiiA/OCYQ+cDttwfcgKLzqf40oG3gJlOF7pUIoVk5L Received: from tapette.crustytoothpaste.net (unknown [IPv6:2001:470:b056:101:e59a:3ed0:5f5c:31f3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (prime256v1) server-digest SHA256) (No client certificate requested) by complex.crustytoothpaste.net (Postfix) with ESMTPSA id E2647209AB; Tue, 9 Jul 2024 23:38:53 +0000 (UTC) From: "brian m. carlson" To: Cc: Junio C Hamano , Johannes Schindelin , Eric Sunshine , Derrick Stolee , Jeff King Subject: [PATCH v4 2/4] gitfaq: give advice on using eol attribute in gitattributes Date: Tue, 9 Jul 2024 23:37:44 +0000 Message-ID: <20240709233746.445860-3-sandals@crustytoothpaste.net> X-Mailer: git-send-email 2.45.2.753.g447d99e1c3b In-Reply-To: <20240709233746.445860-1-sandals@crustytoothpaste.net> References: <20240704003818.750223-1-sandals@crustytoothpaste.net> <20240709233746.445860-1-sandals@crustytoothpaste.net> Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 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 --- Documentation/gitfaq.txt | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt index e4125b1178..058ef32a97 100644 --- a/Documentation/gitfaq.txt +++ b/Documentation/gitfaq.txt @@ -393,8 +393,9 @@ I'm on Windows and git diff shows my files as having a `^M` at the end.:: + You can store the files in the repository with Unix line endings and convert them automatically to your platform's line endings. To do that, set the -configuration option `core.eol` to `native` and see the following entry for -information about how to configure files as text or binary. +configuration option `core.eol` to `native` and see +<> +for information about how to configure files as text or binary. + You can also control this behavior with the `core.whitespace` setting if you don't wish to remove the carriage returns from your line endings. @@ -456,14 +457,26 @@ references, URLs, and hashes stored in the repository. + We also recommend setting a linkgit:gitattributes[5] file to explicitly mark which files are text and which are binary. If you want Git to guess, you can -set the attribute `text=auto`. For example, the following might be appropriate -in some projects: +set the attribute `text=auto`. ++ +With text files, Git will generally ensure that LF endings are used in the +repository. The `core.autocrlf` and `core.eol` configuration variables specify +what line-ending convention is followed when any text file is checked out. You +can also use the `eol` attribute (e.g., `eol=crlf`) to override which files get +what line-ending treatment. ++ +For example, generally shell files must have LF endings and batch files must +have CRLF endings, so the following might be appropriate in some projects: + ---- # By default, guess. * text=auto # Mark all C files as text. *.c text +# Ensure all shell files have LF endings and all batch files have CRLF +# endings in the working tree and both have LF in the repo. +*.sh text eol=lf +*.bat text eol=crlf # Mark all JPEG files as binary. *.jpg binary ---- From patchwork Tue Jul 9 23:37:45 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "brian m. carlson" X-Patchwork-Id: 13728629 Received: from complex.crustytoothpaste.net (complex.crustytoothpaste.net [172.105.7.114]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id B9E0A189F52 for ; Tue, 9 Jul 2024 23:38:54 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=172.105.7.114 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1720568337; cv=none; b=Fkk8gC4rXgZdRG0+Fzd4VbLHXJ8s9ogtevKdRGtYj0eIsOTIgUm+DD/OQWTvD4CncVpgqflsOtUbvcPSAfFM2eIwfgWZfFXv6aC7H8Z731FSl1lyFCHF4m8//ekjEUkfbvWpf5JuEMXhQw6g0WLPID+5/mN5WIpgV9wkJzGI9F4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1720568337; c=relaxed/simple; bh=jGZp7Mb5OBvr6LExuUPybXPNVu1R6EKwPS8jnYgnHa8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=YF81ACeeHea1skMSYzhdiuirMxnx/tgDHbgKbhZCSQUZaYZb6rjIRIqUEBQAJGW5oLNIEwaxCc6JQQ+dbN889jyjdz+5z38Nf1yHCrCDVaFneAbgaT/8H2uB1g7xFDW2Eo7s/nnk95Cd3fjgIE4EMp9e1EEsacfBvBanxCAjsyU= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=crustytoothpaste.net; spf=pass smtp.mailfrom=crustytoothpaste.net; dkim=pass (3072-bit key) header.d=crustytoothpaste.net header.i=@crustytoothpaste.net header.b=OroW1vsd; arc=none smtp.client-ip=172.105.7.114 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=crustytoothpaste.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=crustytoothpaste.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (3072-bit key) header.d=crustytoothpaste.net header.i=@crustytoothpaste.net header.b="OroW1vsd" DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=crustytoothpaste.net; s=default; t=1720568334; bh=jGZp7Mb5OBvr6LExuUPybXPNVu1R6EKwPS8jnYgnHa8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From:Reply-To: Subject:Date:To:CC:Resent-Date:Resent-From:Resent-To:Resent-Cc: In-Reply-To:References:Content-Type:Content-Disposition; b=OroW1vsdriMQifddz9nIl5enUyq4M5NV10P82ZIsEImsKiPeYxs42j9drSehCcc7t c+mPD037PJwS0UVgjHzDSrp0MuUqj9Nz7vnFoyM68wDWjxTk0yh76lz+kEaBJenzFm VWyxtFQJbSaiS/xdldHm1yMrjxI+r72zb0QcXfoHHa59KsafEB9Z8lKkYG0Ueydqy9 INH7H9vpARbaXycjJBEaopWfdhsHlEZZafDmSpL75k9nBSk5nBbnSLaLPZXtmSrQlY Cs5N1Nzf5vyUSvw1Pz2WQ95MSikSVKr8uoZIdN74+qVPa7OOPx5gQC2RzqPnYqTU/I Fbsw1yevV9euOUttSmLS9K1Ep2Ey8zKI8R8CsZ/+6kqcB3A9VVvmhK91ROSngbQ3iM BsDuKrvRb/GZVVgf2XxHV4wt7yXwN52g32urM6ME9/ODP4fpxWdh/dLcNSuGjsKEvS XPyhtqNMot7JbVSxYIJ7ZAJH/1d2popGPgujgGm1FmCYQWTNNDS Received: from tapette.crustytoothpaste.net (unknown [IPv6:2001:470:b056:101:e59a:3ed0:5f5c:31f3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (prime256v1) server-digest SHA256) (No client certificate requested) by complex.crustytoothpaste.net (Postfix) with ESMTPSA id F04BB209AC; Tue, 9 Jul 2024 23:38:53 +0000 (UTC) From: "brian m. carlson" To: Cc: Junio C Hamano , Johannes Schindelin , Eric Sunshine , Derrick Stolee , Jeff King Subject: [PATCH v4 3/4] gitfaq: add entry about syncing working trees Date: Tue, 9 Jul 2024 23:37:45 +0000 Message-ID: <20240709233746.445860-4-sandals@crustytoothpaste.net> X-Mailer: git-send-email 2.45.2.753.g447d99e1c3b In-Reply-To: <20240709233746.445860-1-sandals@crustytoothpaste.net> References: <20240704003818.750223-1-sandals@crustytoothpaste.net> <20240709233746.445860-1-sandals@crustytoothpaste.net> Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 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 --- Documentation/gitfaq.txt | 52 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt index 058ef32a97..f2917d142c 100644 --- a/Documentation/gitfaq.txt +++ b/Documentation/gitfaq.txt @@ -185,6 +185,58 @@ Then, you can adjust your push URL to use `git@example_author` or `git@example_committer` instead of `git@example.org` (e.g., `git remote set-url git@example_author:org1/project1.git`). +Transfers +--------- + +[[sync-working-tree]] +How do I sync a working tree across systems?:: + First, decide whether you want to do this at all. Git works best when you + push or pull your work using the typical `git push` and `git fetch` commands + and isn't designed to share a working tree across systems. This is + potentially risky and in some cases can cause repository corruption or data + loss. ++ +Usually, doing so will cause `git status` to need to re-read every file in the +working tree. Additionally, Git's security model does not permit sharing a +working tree across untrusted users, so it is only safe to sync a working tree +if it will only be used by a single user across all machines. ++ +It is important not to use a cloud syncing service to sync any portion of a Git +repository, since this can cause corruption, such as missing objects, changed +or added files, broken refs, and a wide variety of other problems. These +services tend to sync file by file on a continuous basis and don't understand +the structure of a Git repository. This is especially bad if they sync the +repository in the middle of it being updated, since that is very likely to +cause incomplete or partial updates and therefore data loss. ++ +An example of the kind of corruption that can occur is conflicts over the state +of refs, such that both sides end up with different commits on a branch that +the other doesn't have. This can result in important objects becoming +unreferenced and possibly pruned by `git gc`, causing data loss. ++ +Therefore, it's better to push your work to either the other system or a central +server using the normal push and pull mechanism. However, this doesn't always +preserve important data, like stashes, so some people prefer to share a working +tree across systems. ++ +If you do this, the recommended approach is to use `rsync -a --delete-after` +(ideally with an encrypted connection such as with `ssh`) on the root of +repository. You should ensure several things when you do this: ++ +* If you have additional worktrees or a separate Git directory, they must be + synced at the same time as the main working tree and repository. +* You are comfortable with the destination directory being an exact copy of the + source directory, _deleting any data that is already there_. +* The repository (including all worktrees and the Git directory) is in a + quiescent state for the duration of the transfer (that is, no operations of + any sort are taking place on it, including background operations like `git + gc` and operations invoked by your editor). ++ +Be aware that even with these recommendations, syncing in this way has some risk +since it bypasses Git's normal integrity checking for repositories, so having +backups is advised. You may also wish to do a `git fsck` to verify the +integrity of your data on the destination system after syncing. + Common Issues ------------- From patchwork Tue Jul 9 23:37:46 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "brian m. carlson" X-Patchwork-Id: 13728630 Received: from complex.crustytoothpaste.net (complex.crustytoothpaste.net [172.105.7.114]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id BC641189F54 for ; Tue, 9 Jul 2024 23:38:54 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=172.105.7.114 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1720568337; cv=none; b=jWsukdpbJ604Ko8vGTgJnoMDlVl4JiMGqL45QvOIwVDQ3TZlJd+ouX9w2tqb5azuUEEhOt6Ynqjb2qbLf7n4z0wZrXm8VX4FDuPh23LYSZ1HzgZaEgfSdQYW9hnSx82bv/G7m3kzIYLFGnwhNkiNbqjbqQ5dKuwTrj9zxgN8AQc= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1720568337; c=relaxed/simple; bh=Ddpg71eDm99y1YtJE85ulYA4kSVEGfhXpF2+21TIyt8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=ibCTZja+mACoLa6C4QqyHonO16zLDWw+/2sQf+izUm4W+90PAez+AxpP+2wtqPqHauZJ3KOJwVha/GD8keXYzcM0Vzdi0gT3oaR/R781jHTdDg+Hmo3FxRPy84diW/UW5luvfPU0OL0HOfSIfzezdbuCl4Udzyg/+JbmbtLXts4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=crustytoothpaste.net; spf=pass smtp.mailfrom=crustytoothpaste.net; dkim=pass (3072-bit key) header.d=crustytoothpaste.net header.i=@crustytoothpaste.net header.b=F/5Q36hI; arc=none smtp.client-ip=172.105.7.114 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=crustytoothpaste.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=crustytoothpaste.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (3072-bit key) header.d=crustytoothpaste.net header.i=@crustytoothpaste.net header.b="F/5Q36hI" DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=crustytoothpaste.net; s=default; t=1720568334; bh=Ddpg71eDm99y1YtJE85ulYA4kSVEGfhXpF2+21TIyt8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From:Reply-To: Subject:Date:To:CC:Resent-Date:Resent-From:Resent-To:Resent-Cc: In-Reply-To:References:Content-Type:Content-Disposition; b=F/5Q36hI7Gi8to9/cILUCTGBV3JfOWGmuul0NQ1wJXbJ/EabrxQbOdh6VZ8QPCD9F uR3E42VnvBBawbWYuAgtYFgNULnDm29RGcBHt2nwFcaesOn5tHhKDHj8HUWU62uz+G reF7HKSo4zTtkG15khSNQoqI7qeIpEP2Yu5RKWCDndpnRKwq73+byanSdkZMS2N2RY xX5CRXz4OnS/UfuzxGVfp3j9mnLwUOT/nV09FWC9WU02ZWH0NTcqthNUb5r1FeR4uU cYjW/ypKLpbwG0e9qtmjpB5BE1D7ydt3vsGNui5sszDQPR4Vc86516pGj7XV+VLqpF J6L4LsEBMPn5RJsoD9enNQMFDNED4a+YgWQJpn3iTorjBBo/J6kiHKUpm1gLZN/Y/N YUUyI2E7Dc0fPP2XjbmnQorE1AuUXCMn+do7Yvcn9WxcpUQHBOwWHkMoBQV5zhNZVQ NJUF3dAMxNkOq7YUogg4wYsiT9M6lLcTpW1AnyglTHf0tclt6Kp Received: from tapette.crustytoothpaste.net (unknown [IPv6:2001:470:b056:101:e59a:3ed0:5f5c:31f3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (prime256v1) server-digest SHA256) (No client certificate requested) by complex.crustytoothpaste.net (Postfix) with ESMTPSA id 0A3BA209AD; Tue, 9 Jul 2024 23:38:54 +0000 (UTC) From: "brian m. carlson" To: Cc: Junio C Hamano , Johannes Schindelin , Eric Sunshine , Derrick Stolee , Jeff King Subject: [PATCH v4 4/4] doc: mention that proxies must be completely transparent Date: Tue, 9 Jul 2024 23:37:46 +0000 Message-ID: <20240709233746.445860-5-sandals@crustytoothpaste.net> X-Mailer: git-send-email 2.45.2.753.g447d99e1c3b In-Reply-To: <20240709233746.445860-1-sandals@crustytoothpaste.net> References: <20240704003818.750223-1-sandals@crustytoothpaste.net> <20240709233746.445860-1-sandals@crustytoothpaste.net> Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 We already document in the FAQ that proxies must be completely transparent and not modify the request or response in any way, but add similar documentation to the http.proxy entry. We know that while the FAQ is very useful, users sometimes are less likely to read in favor of the documentation specific to an option or command, so adding it in both places will help users be adequately informed. Signed-off-by: brian m. carlson --- Documentation/config/http.txt | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/Documentation/config/http.txt b/Documentation/config/http.txt index 2d4e0c9b86..a9c7480f6a 100644 --- a/Documentation/config/http.txt +++ b/Documentation/config/http.txt @@ -7,6 +7,11 @@ http.proxy:: linkgit:gitcredentials[7] for more information. The syntax thus is '[protocol://][user[:password]@]proxyhost[:port]'. This can be overridden on a per-remote basis; see remote..proxy ++ +Any proxy, however configured, must be completely transparent and must not +modify, transform, or buffer the request or response in any way. Proxies which +are not completely transparent are known to cause various forms of breakage +with Git. http.proxyAuthMethod:: Set the method with which to authenticate against the HTTP proxy. This