From patchwork Wed Oct 20 01:06:20 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "brian m. carlson" X-Patchwork-Id: 12571459 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 13448C433F5 for ; Wed, 20 Oct 2021 01:07:04 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id E73A660F9E for ; Wed, 20 Oct 2021 01:07:03 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230017AbhJTBJQ (ORCPT ); Tue, 19 Oct 2021 21:09:16 -0400 Received: from injection.crustytoothpaste.net ([192.241.140.119]:37026 "EHLO injection.crustytoothpaste.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229686AbhJTBJQ (ORCPT ); Tue, 19 Oct 2021 21:09:16 -0400 Received: from camp.crustytoothpaste.net (unknown [IPv6:2001:470:b056:101:a6ae:7d13:8741:9028]) (using TLSv1.2 with cipher ECDHE-RSA-CHACHA20-POLY1305 (256/256 bits)) (No client certificate requested) by injection.crustytoothpaste.net (Postfix) with ESMTPSA id 160A860769; Wed, 20 Oct 2021 01:06:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=crustytoothpaste.net; s=default; t=1634691992; bh=UbTsTPMWAQw2Tf/DkJ6XCCL0SzZU0+a9mb1YEiyyEBQ=; 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=mGcrLMYa/YlEW5QHZ+LHSvZ9YXn+Us1CjtUeUxGiE6k+xecysVWNpX099ae1vqSjB DxDGZ2wdCHNkp9QCb72G0AExQFLwKmY97Q4qfAK1h3ywBZA0wAPhJaP6B5jRwQ77Jl Qqlwnprs8GK9IzYEY+U/yMqN1Fus6oFjoniLKoP3fcTPwPTwR5lysOcLvJCQMwKdLa W74e6hA9qKsQobByinp2Ir+Axyar6t5bdN/GqRn9nb97ep0g/ruFEtOxG7T1BH+lZ7 TUx5IBWDitzLGq1RT5hc7vS0XpXgPZ4Ff//gO/fL/pYEQ/GCsAQQ8H5fKV78K/FDAV 96U2ikbbEYVi2NWor+jbrKhw+36GA+W6L1ngXiedGKd4PEGxftBiNYQUXTBHWVcimq 4r76G9ow9x1hsI5uR0ggksc5UAP1b/LIl9aRhVo3f1M95mkM3HWJ5LPTPgLrecpTUZ MVlCWBQpIJnXk3nIqSr4d73jblvtL0E/PDdVe89bg1/g9CWzegM From: "brian m. carlson" To: Cc: Jeff King , Johannes Schindelin , Derrick Stolee Subject: [PATCH 1/4] gitfaq: add advice on monorepos Date: Wed, 20 Oct 2021 01:06:20 +0000 Message-Id: <20211020010624.675562-2-sandals@crustytoothpaste.net> X-Mailer: git-send-email 2.33.0.882.g93a45727a2 In-Reply-To: <20211020010624.675562-1-sandals@crustytoothpaste.net> References: <20211020010624.675562-1-sandals@crustytoothpaste.net> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org Many projects around the world have chosen monorepos, and active development on Git is ongoing to support them better. However, as projects using monorepos grow, they often find various performance and scalability problems that are unpleasant to deal with. Add a FAQ entry to note that while Git is attempting improvements in this area, it is not uncommon to see performance problems that necessitate the use of partial or shallow clone, sparse checkout, or the like, and that if users wish to avoid these problems, avoiding a monorepo may be best. Signed-off-by: brian m. carlson --- Documentation/gitfaq.txt | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt index 8c1f2d5675..946691c153 100644 --- a/Documentation/gitfaq.txt +++ b/Documentation/gitfaq.txt @@ -241,6 +241,32 @@ 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]. +Design +------ + +[[monorepos]] +Should we use a monorepo or many individual repos?:: + This is a decision that is typically made based on an organization's needs and + desires for their projects. Git has several features, such as shallow clone, + partial clone, and sparse checkout to make working with large repositories + easier, and there is active development on making the monorepo experience + better. ++ +However, at a certain size, the performance of a monorepo will likely become +unacceptable _unless_ you use these features. If you choose to start with a +monorepo and continue to grow, you may end up unhappy with the performance +characteristics at a point where making a change is difficult. The performance +of using many smaller repositories will almost always be much better and will +generally not necessitate the use of these more advanced features. If you are +concerned about future performance of your repository and related tools, you may +wish to avoid a monorepo. ++ +Ultimately, you should make a decision fully informed about the potential +benefits and downsides, including the capabilities, performance, and future +requirements for your repository and related tools, including your hosting +platform, build tools, and other programs you typically use as part of your +workflow. + Merging and Rebasing -------------------- From patchwork Wed Oct 20 01:06:21 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "brian m. carlson" X-Patchwork-Id: 12571461 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 919D8C433FE for ; Wed, 20 Oct 2021 01:07:04 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 7316A600D3 for ; Wed, 20 Oct 2021 01:07:04 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230061AbhJTBJR (ORCPT ); Tue, 19 Oct 2021 21:09:17 -0400 Received: from injection.crustytoothpaste.net ([192.241.140.119]:37028 "EHLO injection.crustytoothpaste.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229741AbhJTBJQ (ORCPT ); Tue, 19 Oct 2021 21:09:16 -0400 Received: from camp.crustytoothpaste.net (unknown [IPv6:2001:470:b056:101:a6ae:7d13:8741:9028]) (using TLSv1.2 with cipher ECDHE-RSA-CHACHA20-POLY1305 (256/256 bits)) (No client certificate requested) by injection.crustytoothpaste.net (Postfix) with ESMTPSA id 459D260786; Wed, 20 Oct 2021 01:06:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=crustytoothpaste.net; s=default; t=1634691992; bh=0glHI5VDiJIwIWZYs/4kKFoRVfdx+35K9YtLrLK/mdE=; 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=IW4z8BkPBUNnuubKkgqvGUUQ0qqgcKJlJE+0+0HSxGk8k80RDR85SJ+epgnNInXAp hzXgi9nklanfZis/pp3GMBJ+o82eArTmggk+hlF8z1s1xf3FXmtqZDnU8dpJSliAMk VUg/BaNZ0JyJjYpFQ14JQkF4nTsns3vIorUbJ6znVbaQulQkQge6POngqLktT5XY5R poLGhTvHMIdOiaI5uVPZuwD7DTIVAXXdh/Gf2ka70UhWo7CnqQ7CF7jok26BJ7/LZW xtWl9No05FIQwpeVnfIoFlIyqFYQ+oUg3at0zEF/yzrRKPJLT7jKgvGFyCY5fbye14 /mr7i/pLO/0H2FuUS0Yh8L8aS7mVQ6PdvKeo2dQxFSrdOTRkfhQShmLLZmQiwtgOHD O0pIsr72nVGFKD+lrRZ7oWc86sumvMugppACNCu9rZuFN2KN3fR/sPz1K0FK1k+UcK H0yiUW8kH2w8TojZBV3amUF8+Fmf/netiHdr9gB3wqO0QXWEgIS From: "brian m. carlson" To: Cc: Jeff King , Johannes Schindelin , Derrick Stolee Subject: [PATCH 2/4] gitfaq: add documentation on proxies Date: Wed, 20 Oct 2021 01:06:21 +0000 Message-Id: <20211020010624.675562-3-sandals@crustytoothpaste.net> X-Mailer: git-send-email 2.33.0.882.g93a45727a2 In-Reply-To: <20211020010624.675562-1-sandals@crustytoothpaste.net> References: <20211020010624.675562-1-sandals@crustytoothpaste.net> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org 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. Signed-off-by: brian m. carlson --- Documentation/gitfaq.txt | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt index 946691c153..abc0f62e6c 100644 --- a/Documentation/gitfaq.txt +++ b/Documentation/gitfaq.txt @@ -241,6 +241,24 @@ 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. ++ +However, note that for Git to work properly, the proxy must be completely +transparent. The proxy cannot modify, tamper with, change, 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, we recommend against the use of these classes of +software and devices. + Design ------ From patchwork Wed Oct 20 01:06:22 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "brian m. carlson" X-Patchwork-Id: 12571453 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 5C071C433F5 for ; Wed, 20 Oct 2021 01:06:35 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 34A1A610FC for ; Wed, 20 Oct 2021 01:06:35 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229910AbhJTBIr (ORCPT ); Tue, 19 Oct 2021 21:08:47 -0400 Received: from injection.crustytoothpaste.net ([192.241.140.119]:37008 "EHLO injection.crustytoothpaste.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229677AbhJTBIq (ORCPT ); Tue, 19 Oct 2021 21:08:46 -0400 Received: from camp.crustytoothpaste.net (unknown [IPv6:2001:470:b056:101:a6ae:7d13:8741:9028]) (using TLSv1.2 with cipher ECDHE-RSA-CHACHA20-POLY1305 (256/256 bits)) (No client certificate requested) by injection.crustytoothpaste.net (Postfix) with ESMTPSA id 7C2B060795; Wed, 20 Oct 2021 01:06:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=crustytoothpaste.net; s=default; t=1634691992; bh=yIZPYXOfzG0y4x1BLigMTh0K/e/zAR7jUYLrODIgg44=; 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=WHLfjTBWNnHbLogRmIa0bB5TYRklmF+YORmB1yKEfH93WImmBocxDA/7jNP2ecec9 MLP8+Qcw+yfwL/8C66xBMEkIoZ8be6d9tomNk1LZyB4TQCpdg1XZ3fOqJhjKdLwO/y 0KEYl1TPBgx3pgPhq1JLCbSEtXR+MCL+U+++69ynMG0xelZJDjFuBFg0umeQqetORQ bb7dSDAd2VhN54ZcwqvrJVDKcCk7S0ho+zc9bCFU1RnzNNSVfNvA5fHTiEVPAu0df+ KYfFOiuKQCHK9Aa5ChlN6hHWiq7MMQbyBuNPct4wJ+of+Wk/XqcQNUzpXzp/FvYUM7 WrivxyXjbXwHlH2LGxfC7FrLgI0sDfpdsyxxgs3l/KVSJ9boQ801IWwciriSBagDKr IL8UqztQ9hh1eT+5Af4iadz75AQY09WRSW2tvQiH1SbE1F10rnrx2kTseUnRZS1r4L wua3+pxkK0BOax2VnJi6osv32fbP+8Ss10+BgPmWUq+HHinw/3e From: "brian m. carlson" To: Cc: Jeff King , Johannes Schindelin , Derrick Stolee Subject: [PATCH 3/4] gitfaq: give advice on using eol attribute in gitattributes Date: Wed, 20 Oct 2021 01:06:22 +0000 Message-Id: <20211020010624.675562-4-sandals@crustytoothpaste.net> X-Mailer: git-send-email 2.33.0.882.g93a45727a2 In-Reply-To: <20211020010624.675562-1-sandals@crustytoothpaste.net> References: <20211020010624.675562-1-sandals@crustytoothpaste.net> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org 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 | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt index abc0f62e6c..85ac99c7b2 100644 --- a/Documentation/gitfaq.txt +++ b/Documentation/gitfaq.txt @@ -401,8 +401,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. @@ -464,14 +465,25 @@ 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 the repository contains LF endings in the +repository, and will honor `core.autocrlf` and `core.eol` to decide what options +to use when checking files out. You can also override this by specifying a +particular line ending such as `eol=lf` or `eol=crlf` if those files must always +have that ending (e.g., for functionality reasons). ++ +For example, 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 end up with LF endings and all batch files end up +# with CRLF endings in the working tree and both end up with LF in the repo. +*.sh text eol=lf +*.bat text eol=crlf # Mark all JPEG files as binary. *.jpg binary ---- From patchwork Wed Oct 20 01:06:23 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "brian m. carlson" X-Patchwork-Id: 12571455 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 2E9C7C433F5 for ; Wed, 20 Oct 2021 01:06:37 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 0FF036113B for ; Wed, 20 Oct 2021 01:06:37 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229985AbhJTBIs (ORCPT ); Tue, 19 Oct 2021 21:08:48 -0400 Received: from injection.crustytoothpaste.net ([192.241.140.119]:37016 "EHLO injection.crustytoothpaste.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229686AbhJTBIq (ORCPT ); Tue, 19 Oct 2021 21:08:46 -0400 Received: from camp.crustytoothpaste.net (unknown [IPv6:2001:470:b056:101:a6ae:7d13:8741:9028]) (using TLSv1.2 with cipher ECDHE-RSA-CHACHA20-POLY1305 (256/256 bits)) (No client certificate requested) by injection.crustytoothpaste.net (Postfix) with ESMTPSA id ADB9260D01; Wed, 20 Oct 2021 01:06:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=crustytoothpaste.net; s=default; t=1634691992; bh=S4IMMovLTKF9YmTInA45gWjXq7INKAXkYrxCInX1wkA=; 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=zkVfECUwsYexrQy7kmzfSZUYws5WIQWNpnqxZW+ntlg+oAG1ZmwGaxsRG320f5tuO 14Wr9PfKRHpc9i9SH1L6wdSD+C4FK+KddCI6SxBmP4nBaB2vXOCThIN/60DAXMtiwF k0zAotWLDF3bja7ivRqFEUG51aK9Yg8+0n5cHyRTaF7i1yj8mb/zmCY+OhQlcxMwLO Y2Bn4BgHtSwpaO9RYO9M/CR8nh2sWRFzTNZvh6fD/7NuHyRoVCzkPU2zwp91B12Rny ch0rI3Nz5UHA/7ack3DsBNmgE0NA++c7CbFi/k+TnIzq0Dq2KWm+5+/aiVCjDGNHud 5H+c0wySUPKqztE3cTCW1WAcjOyTAa+NdnW9hzmhx+S0Rheeq2wuYHiBdmZIkteV42 noOBErp7DHz3N+mPYMyeIar2dXf0/uzj/wlGNaVyFQt+NWjCH90zsOQa2Gztzc2Zvu rWB07mUe78RBQaQlbidSmZsYEm6BwGANAvqzi4aPsTWAF+v49oC From: "brian m. carlson" To: Cc: Jeff King , Johannes Schindelin , Derrick Stolee Subject: [PATCH 4/4] doc: add a FAQ entry about syncing working trees Date: Wed, 20 Oct 2021 01:06:23 +0000 Message-Id: <20211020010624.675562-5-sandals@crustytoothpaste.net> X-Mailer: git-send-email 2.33.0.882.g93a45727a2 In-Reply-To: <20211020010624.675562-1-sandals@crustytoothpaste.net> References: <20211020010624.675562-1-sandals@crustytoothpaste.net> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org Users very commonly want to sync their working tree 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 | 43 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 41 insertions(+), 2 deletions(-) diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt index 85ac99c7b2..4a8a46f980 100644 --- a/Documentation/gitfaq.txt +++ b/Documentation/gitfaq.txt @@ -83,8 +83,8 @@ Windows would be the configuration `"C:\Program Files\Vim\gvim.exe" --nofork`, which quotes the filename with spaces and specifies the `--nofork` option to avoid backgrounding the process. -Credentials ------------ +Credentials and Transfers +------------------------- [[http-credentials]] How do I specify my credentials when pushing over HTTP?:: @@ -185,6 +185,45 @@ 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`). +[[sync-working-tree]] +How do I sync a working tree across systems?:: + First, decide whether you want to do this at all. Git usually works better + 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. Doing so + can 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. ++ +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. ++ +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 corruption. These +services tend to sync file by file 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. ++ +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: ++ +* There are no additional worktrees enabled for your repository. +* You are not using a separate Git directory outside of your repository root. +* You are comfortable with the destination directory being an exact copy of the + source directory, _deleting any data that is already there_. +* The repository 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`). ++ +Be aware that even with these recommendations, syncing in this way is +potentially risky since it bypasses Git's normal integrity checking for +repositories, so having backups is advised. + Common Issues -------------