{"thread":{"id":"52681","subject":"[PATCH] git: update documentation for --git-dir","startedAt":"2020-01-23T02:16:56Z","lastAt":"2020-01-30T18:26:26Z","messageCount":17,"participants":["Heba Waly via GitGitGadget","Heba Waly","Emily Shaffer","Junio C Hamano","Johannes Sixt","Jeff King"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"390252","messageId":"pull.537.git.1579745811615.gitgitgadget@gmail.com","threadId":"52681","inReplyTo":null,"subject":"[PATCH] git: update documentation for --git-dir","fromName":"Heba Waly via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2020-01-23T02:16:51Z","receivedAt":"2020-01-23T02:16:56Z","isPatch":true,"sender":{"key":"heba.waly@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1539076?v=4"},"body":"From: Heba Waly \n\ngit --git-dir is a bit confusing and sometimes doesn't work as\nthe user would expect it to.\n\nFor example, if the user runs `git --git-dir= status`, git\nwill not be able to figure out the work tree path on its own and\nwill assign the work tree to the user's current work directory.\nWhen this assignment is wrong, then the output will not match the\nuser's expectations.\n\nThis patch updates the documentation to make it clearer.\n\nSigned-off-by: Heba Waly \n---\n [Outreachy] git: update documentation for --git-dir\n \n git --git-dir is a bit confusing and sometimes doesn't work as the user\n would expect it to.\n \n For example, if the user runs git --git-dir= status, git will not\n be able to figure out the work tree path on its own and will assign the\n work tree to the user's current work directory. When this assignment is\n wrong, then the output will not match the user's expectations.\n \n This patch updates the documentation to make it clearer.\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-537%2FHebaWaly%2Fgit_dir_doc-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-537/HebaWaly/git_dir_doc-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/537\n\n Documentation/git.txt | 13 +++++++++----\n 1 file changed, 9 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex b1597ac002..3b9402c742 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -110,10 +110,15 @@ foo.bar= ...`) sets `foo.bar` to the empty string which `git config\n \tDo not pipe Git output into a pager.\n \n --git-dir=::\n-\tSet the path to the repository. This can also be controlled by\n-\tsetting the `GIT_DIR` environment variable. It can be an absolute\n-\tpath or relative path to current working directory.\n-\n+\tSet the path to the repository (i.e. the .git folder). This can also be\n+\tcontrolled by setting the `GIT_DIR` environment variable. It can be\n+\tan absolute path or relative path to current working directory.\n+\n+\tNote that --git-dir= is not the same as -C=.\n+\tIt's preferrable to set --work-tree= as well when setting\n+\t--git-dir to make sure Git will run your command across the correct\n+\twork tree.\n+\t\n --work-tree=::\n \tSet the path to the working tree. It can be an absolute path\n \tor a path relative to the current working directory.\n\nbase-commit: 232378479ee6c66206d47a9be175e3a39682aea6\n-- \ngitgitgadget\n"},{"id":"390253","messageId":"CACg5j25uCHgaANtVyEHNqKcZoQG=NyrsgZAtdqo8oLcbZFkP4w@mail.gmail.com","threadId":"52681","inReplyTo":"pull.537.git.1579745811615.gitgitgadget@gmail.com","subject":"Re: [PATCH] git: update documentation for --git-dir","fromName":"Heba Waly","fromEmail":"heba.waly@gmail.com","sentAt":"2020-01-23T02:35:49Z","receivedAt":"2020-01-23T02:36:03Z","isPatch":true,"sender":{"key":"heba.waly@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1539076?v=4"},"body":"On Thu, Jan 23, 2020 at 3:16 PM Heba Waly via GitGitGadget\n wrote:\n>\n> From: Heba Waly \n>\n> git --git-dir is a bit confusing and sometimes doesn't work as\n> the user would expect it to.\n>\n> For example, if the user runs `git --git-dir= status`, git\n> will not be able to figure out the work tree path on its own and\n> will assign the work tree to the user's current work directory.\n> When this assignment is wrong, then the output will not match the\n> user's expectations.\n>\n> This patch updates the documentation to make it clearer.\n>\n> Signed-off-by: Heba Waly \n> ---\n> [Outreachy] git: update documentation for --git-dir\n>\n> git --git-dir is a bit confusing and sometimes doesn't work as the user\n> would expect it to.\n>\n> For example, if the user runs git --git-dir= status, git will not\n> be able to figure out the work tree path on its own and will assign the\n> work tree to the user's current work directory. When this assignment is\n> wrong, then the output will not match the user's expectations.\n>\n> This patch updates the documentation to make it clearer.\n>\n> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-537%2FHebaWaly%2Fgit_dir_doc-v1\n> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-537/HebaWaly/git_dir_doc-v1\n> Pull-Request: https://github.com/gitgitgadget/git/pull/537\n>\n> Documentation/git.txt | 13 +++++++++----\n> 1 file changed, 9 insertions(+), 4 deletions(-)\n>\n> diff --git a/Documentation/git.txt b/Documentation/git.txt\n> index b1597ac002..3b9402c742 100644\n> --- a/Documentation/git.txt\n> +++ b/Documentation/git.txt\n> @@ -110,10 +110,15 @@ foo.bar= ...`) sets `foo.bar` to the empty string which `git config\n> Do not pipe Git output into a pager.\n>\n> --git-dir=::\n> - Set the path to the repository. This can also be controlled by\n> - setting the `GIT_DIR` environment variable. It can be an absolute\n> - path or relative path to current working directory.\n> -\n> + Set the path to the repository (i.e. the .git folder). This can also be\n> + controlled by setting the `GIT_DIR` environment variable. It can be\n> + an absolute path or relative path to current working directory.\n> +\n> + Note that --git-dir= is not the same as -C=.\n> + It's preferrable to set --work-tree= as well when setting\n> + --git-dir to make sure Git will run your command across the correct\n> + work tree.\n> +\n\nI just noticed the whitespace on the last line, will wait for the\npatch to be reviewed then include its fix.\n\n> --work-tree=::\n> Set the path to the working tree. It can be an absolute path\n> or a path relative to the current working directory.\n>\n> base-commit: 232378479ee6c66206d47a9be175e3a39682aea6\n> --\n> gitgitgadget\n"},{"id":"390254","messageId":"20200123025521.GA126375@google.com","threadId":"52681","inReplyTo":"pull.537.git.1579745811615.gitgitgadget@gmail.com","subject":"Re: [PATCH] git: update documentation for --git-dir","fromName":"Emily Shaffer","fromEmail":"emilyshaffer@google.com","sentAt":"2020-01-23T02:55:21Z","receivedAt":"2020-01-23T02:55:29Z","isPatch":true,"sender":{"key":"nasamuffin@google.com","avatar":"https://avatars.githubusercontent.com/u/1606826?v=4"},"body":"On Thu, Jan 23, 2020 at 02:16:51AM +0000, Heba Waly via GitGitGadget wrote:\n> From: Heba Waly \n> \n> git --git-dir is a bit confusing and sometimes doesn't work as\n> the user would expect it to.\n> \n> For example, if the user runs `git --git-dir= status`, git\n> will not be able to figure out the work tree path on its own and\n> will assign the work tree to the user's current work directory.\n> When this assignment is wrong, then the output will not match the\n> user's expectations.\n> \n> This patch updates the documentation to make it clearer.\n\nOne thing Heba doesn't mention here is the effort she spent looking into\nhow to give a similar hint in the form of an advise() call in cases when\n--git-dir is specified but --work-tree is not. While it's possible to\nshow that kind of hint, it turns out to be tricky to decide whether the\ncall in question actually wants the worktree. There was also some\nconcern from Jonathan Tan around whether the hint would interfere with\npre-existing user scripts which use --git-dir; since hints show on\nstderr, that interference is likely cosmetic, but still not great.\n\nThat left me with a couple questions:\n\n - Is there a reason the advice library can't check whether it's\n pointing to an interactive shell, along the same lines as deciding\n whether to color output or not?\n - How do we generally worry about changes to stderr output in regard to\n user scripts? Is this as concerning as changes to stdout and return\n code, that is, for plumbing we do not change the format?\n\n> \n> Signed-off-by: Heba Waly \n> ---\n> [Outreachy] git: update documentation for --git-dir\n> \n> git --git-dir is a bit confusing and sometimes doesn't work as the user\n> would expect it to.\n> \n> For example, if the user runs git --git-dir= status, git will not\n> be able to figure out the work tree path on its own and will assign the\n> work tree to the user's current work directory. When this assignment is\n> wrong, then the output will not match the user's expectations.\n> \n> This patch updates the documentation to make it clearer.\n> \n> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-537%2FHebaWaly%2Fgit_dir_doc-v1\n> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-537/HebaWaly/git_dir_doc-v1\n> Pull-Request: https://github.com/gitgitgadget/git/pull/537\n> \n> Documentation/git.txt | 13 +++++++++----\n> 1 file changed, 9 insertions(+), 4 deletions(-)\n> \n> diff --git a/Documentation/git.txt b/Documentation/git.txt\n> index b1597ac002..3b9402c742 100644\n> --- a/Documentation/git.txt\n> +++ b/Documentation/git.txt\n> @@ -110,10 +110,15 @@ foo.bar= ...`) sets `foo.bar` to the empty string which `git config\n> \tDo not pipe Git output into a pager.\n> \n> --git-dir=::\n> -\tSet the path to the repository. This can also be controlled by\n> -\tsetting the `GIT_DIR` environment variable. It can be an absolute\n> -\tpath or relative path to current working directory.\n> -\n> +\tSet the path to the repository (i.e. the .git folder). This can also be\n> +\tcontrolled by setting the `GIT_DIR` environment variable. It can be\n> +\tan absolute path or relative path to current working directory.\n> +\n> +\tNote that --git-dir= is not the same as -C=.\n> +\tIt's preferrable to set --work-tree= as well when setting\n> +\t--git-dir to make sure Git will run your command across the correct\n> +\twork tree.\n\nI feel biased. I want to say, \"In many cases, -C= is easier to\nunderstand than --git-dir\" instead. :) But my goal with sending this\ntask to you was \"convince people to use -C instead of --git-dir unless\nthey're really sure\" - which may or may not align with the sentiment of\nthe rest of the list.\n\n - Emily\n"},{"id":"390258","messageId":"xmqq7e1i66cy.fsf@gitster-ct.c.googlers.com","threadId":"52681","inReplyTo":"pull.537.git.1579745811615.gitgitgadget@gmail.com","subject":"Re: [PATCH] git: update documentation for --git-dir","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-01-23T06:21:01Z","receivedAt":"2020-01-23T06:21:13Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Heba Waly via GitGitGadget\" writes:\n\n> For example, if the user runs `git --git-dir= status`, git\n> will not be able to figure out the work tree path on its own \n\nIt is not \"not be able to figure out\". Specifying GIT_DIR (either\nwith environment or the --git-dir option) tells Git that the $cwd is\nthe top of the working tree unless otherwise specified (e.g. with\nGIT_WORK_TREE environment). If you have to say something, saying\n\"When GIT_DIR is specified, the usual repository discovery is\nskipped and the current directory is taken as the top level of the\nworking tree unless otherwise speciffied\" is probably OK.\n\n"},{"id":"390259","messageId":"xmqq1rrq65ed.fsf@gitster-ct.c.googlers.com","threadId":"52681","inReplyTo":"pull.537.git.1579745811615.gitgitgadget@gmail.com","subject":"Re: [PATCH] git: update documentation for --git-dir","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-01-23T06:41:46Z","receivedAt":"2020-01-23T06:41:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Heba Waly via GitGitGadget\" writes:\n\n> --git-dir=::\n> -\tSet the path to the repository. This can also be controlled by\n> -\tsetting the `GIT_DIR` environment variable. It can be an absolute\n> -\tpath or relative path to current working directory.\n> -\n> +\tSet the path to the repository (i.e. the .git folder). This can also be\n\nI suspect (i.e. \".git\") may be clear enough, but if you must, say\n\".git directory\", not \".git folder\", as you mention \"current working\ndirectory\" later.\n\n> +\tcontrolled by setting the `GIT_DIR` environment variable. It can be\n> +\tan absolute path or relative path to current working directory.\n> +\n> +\tNote that --git-dir= is not the same as -C=.\n\nSurely, of course.\n\n> +\tIt's preferrable to set --work-tree= as well when setting\n> +\t--git-dir to make sure Git will run your command across the correct\n> +\twork tree.\n\nIt does not help the readers that much to say \"It's preferrable\"\nwithout saying what negative implications there are if they don't\nuse it, or what positive effect they would observe if they do.\n\nIf I were writing it, I'd drop \"Note that...\" and rewrite the three\nlines more like...\n\n\tSpecifying the location of the \".git\" directory using this\n\toption (or GIT_DIR environment variable) turns off the\n\trepository discovery that tries to find a directory with\n\t\".git\" subdirectory (which is how the repository and the\n\ttop-level of the working tree are discovered), and tells Git\n\tthat you are at the top level of the working tree. If you\n\tare not at the top-level directory of the working tree, you\n\tshould tell Git where the top-level of the working tree is,\n\twith the --work-tree= option (or GIT_WORK_TREE\n\tenvironment variable)\n\nperhaps.\n\n> --work-tree=::\n> \tSet the path to the working tree. It can be an absolute path\n> \tor a path relative to the current working directory.\n>\n> base-commit: 232378479ee6c66206d47a9be175e3a39682aea6\n\nI do not know if GGG users have control over this, but I'd prefer to\nsee a \"-- \" divider before this \"base-commit: ...\" footer material.\n"},{"id":"390260","messageId":"xmqqwo9i4qq0.fsf@gitster-ct.c.googlers.com","threadId":"52681","inReplyTo":"20200123025521.GA126375@google.com","subject":"Re: [PATCH] git: update documentation for --git-dir","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-01-23T06:44:07Z","receivedAt":"2020-01-23T06:44:13Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Emily Shaffer writes:\n\n> I feel biased. I want to say, \"In many cases, -C= is easier to\n> understand than --git-dir\" instead. :) But my goal with sending this\n> task to you was \"convince people to use -C instead of --git-dir unless\n> they're really sure\" - which may or may not align with the sentiment of\n> the rest of the list.\n\nAhh, OK. \n\nThese two are options for completely different purposes, and I tend\nto agree with you that most users when they misuse --git-dir the do\nwant -C instead.\n"},{"id":"390529","messageId":"CACg5j260t0Q1=5i_The5ARN0qRTDKiwmH-KYN5KqHye+Y_9gig@mail.gmail.com","threadId":"52681","inReplyTo":"xmqq1rrq65ed.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH] git: update documentation for --git-dir","fromName":"Heba Waly","fromEmail":"heba.waly@gmail.com","sentAt":"2020-01-27T02:22:01Z","receivedAt":"2020-01-27T02:22:20Z","isPatch":true,"sender":{"key":"heba.waly@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1539076?v=4"},"body":"On Thu, Jan 23, 2020 at 7:41 PM Junio C Hamano wrote:\n>\n> \"Heba Waly via GitGitGadget\" writes:\n>\n> It is not \"not be able to figure out\". Specifying GIT_DIR (either\n> with environment or the --git-dir option) tells Git that the $cwd is\n> the top of the working tree unless otherwise specified (e.g. with\n> GIT_WORK_TREE environment). If you have to say something, saying\n> \"When GIT_DIR is specified, the usual repository discovery is\n> skipped and the current directory is taken as the top level of the\n> working tree unless otherwise speciffied\" is probably OK.\n>\n\nOk, I didn't understand it as intentional before, will update that.\n\n> > + Set the path to the repository (i.e. the .git folder). This can also be\n>\n> I suspect (i.e. \".git\") may be clear enough, but if you must, say\n> \".git directory\", not \".git folder\", as you mention \"current working\n> directory\" later.\n>\n\nFair enough.\n\n> > + It's preferrable to set --work-tree= as well when setting\n> > + --git-dir to make sure Git will run your command across the correct\n> > + work tree.\n>\n> It does not help the readers that much to say \"It's preferrable\"\n> without saying what negative implications there are if they don't\n> use it, or what positive effect they would observe if they do.\n\nI agree, I couldn't find enough information on the matter to elaborate more.\n\n> If I were writing it, I'd drop \"Note that...\" and rewrite the three\n> lines more like...\n>\n> Specifying the location of the \".git\" directory using this\n> option (or GIT_DIR environment variable) turns off the\n> repository discovery that tries to find a directory with\n> \".git\" subdirectory (which is how the repository and the\n> top-level of the working tree are discovered), and tells Git\n> that you are at the top level of the working tree. If you\n> are not at the top-level directory of the working tree, you\n> should tell Git where the top-level of the working tree is,\n> with the --work-tree= option (or GIT_WORK_TREE\n> environment variable)\n>\n> perhaps.\n\nThat helped me understand it better also, will use this, thanks.\n\n>\n> > --work-tree=::\n> > Set the path to the working tree. It can be an absolute path\n> > or a path relative to the current working directory.\n> >\n> > base-commit: 232378479ee6c66206d47a9be175e3a39682aea6\n>\n> I do not know if GGG users have control over this, but I'd prefer to\n> see a \"-- \" divider before this \"base-commit: ...\" footer material.\n\nNo I don't think I can change this one.\n\nThanks,\nHeba\n"},{"id":"390530","messageId":"pull.537.v2.git.1580091855792.gitgitgadget@gmail.com","threadId":"52681","inReplyTo":"pull.537.git.1579745811615.gitgitgadget@gmail.com","subject":"[PATCH v2] git: update documentation for --git-dir","fromName":"Heba Waly via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2020-01-27T02:24:15Z","receivedAt":"2020-01-27T02:24:20Z","isPatch":true,"sender":{"key":"heba.waly@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1539076?v=4"},"body":"From: Heba Waly \n\ngit --git-dir is a bit confusing and sometimes doesn't work as\nthe user would expect it to.\n\nFor example, if the user runs `git --git-dir= status`, git\nwill skip the repository discovery algorithm and will assign the\nwork tree to the user's current work directory unless otherwise\nspecified. When this assignment is wrong, the output will not match\nthe user's expectations.\n\nThis patch updates the documentation to make it clearer.\n\nSigned-off-by: Heba Waly \nHelped-by: Junio C Hamano \n---\n [Outreachy] git: update documentation for --git-dir\n \n git --git-dir is a bit confusing and sometimes doesn't work as the user\n would expect it to.\n \n For example, if the user runs git --git-dir= status, git will not\n be able to figure out the work tree path on its own and will assign the\n work tree to the user's current work directory. When this assignment is\n wrong, then the output will not match the user's expectations.\n \n This patch updates the documentation to make it clearer.\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-537%2FHebaWaly%2Fgit_dir_doc-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-537/HebaWaly/git_dir_doc-v2\nPull-Request: https://github.com/gitgitgadget/git/pull/537\n\nRange-diff vs v1:\n\n 1: 3ac4b85cdb ! 1: 8a69eecb97 git: update documentation for --git-dir\n @@ -6,14 +6,15 @@\n the user would expect it to.\n \n For example, if the user runs `git --git-dir= status`, git\n - will not be able to figure out the work tree path on its own and\n - will assign the work tree to the user's current work directory.\n - When this assignment is wrong, then the output will not match the\n - user's expectations.\n + will skip the repository discovery algorithm and will assign the\n + work tree to the user's current work directory unless otherwise\n + specified. When this assignment is wrong, the output will not match\n + the user's expectations.\n \n This patch updates the documentation to make it clearer.\n \n Signed-off-by: Heba Waly \n + Helped-by: Junio C Hamano \n \n diff --git a/Documentation/git.txt b/Documentation/git.txt\n --- a/Documentation/git.txt\n @@ -25,16 +26,23 @@\n -\tSet the path to the repository. This can also be controlled by\n -\tsetting the `GIT_DIR` environment variable. It can be an absolute\n -\tpath or relative path to current working directory.\n --\n -+\tSet the path to the repository (i.e. the .git folder). This can also be\n ++\tSet the path to the repository (\".git\" directory). This can also be\n +\tcontrolled by setting the `GIT_DIR` environment variable. It can be\n +\tan absolute path or relative path to current working directory.\n +\n -+\tNote that --git-dir= is not the same as -C=.\n -+\tIt's preferrable to set --work-tree= as well when setting\n -+\t--git-dir to make sure Git will run your command across the correct\n -+\twork tree.\n -+\t\n ++\tSpecifying the location of the \".git\" directory using this\n ++\toption (or GIT_DIR environment variable) turns off the\n ++\trepository discovery that tries to find a directory with\n ++\t\".git\" subdirectory (which is how the repository and the\n ++\ttop-level of the working tree are discovered), and tells Git\n ++\tthat you are at the top level of the working tree. If you\n ++\tare not at the top-level directory of the working tree, you\n ++\tshould tell Git where the top-level of the working tree is,\n ++\twith the --work-tree= option (or GIT_WORK_TREE\n ++\tenvironment variable)\n ++\n ++\tIf you just want to run git as if it was started in then use\n ++\tgit -C.\n + \n --work-tree=::\n \tSet the path to the working tree. It can be an absolute path\n - \tor a path relative to the current working directory.\n\n\n Documentation/git.txt | 20 +++++++++++++++++---\n 1 file changed, 17 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex b1597ac002..cf73f501b6 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -110,9 +110,23 @@ foo.bar= ...`) sets `foo.bar` to the empty string which `git config\n \tDo not pipe Git output into a pager.\n \n --git-dir=::\n-\tSet the path to the repository. This can also be controlled by\n-\tsetting the `GIT_DIR` environment variable. It can be an absolute\n-\tpath or relative path to current working directory.\n+\tSet the path to the repository (\".git\" directory). This can also be\n+\tcontrolled by setting the `GIT_DIR` environment variable. It can be\n+\tan absolute path or relative path to current working directory.\n+\n+\tSpecifying the location of the \".git\" directory using this\n+\toption (or GIT_DIR environment variable) turns off the\n+\trepository discovery that tries to find a directory with\n+\t\".git\" subdirectory (which is how the repository and the\n+\ttop-level of the working tree are discovered), and tells Git\n+\tthat you are at the top level of the working tree. If you\n+\tare not at the top-level directory of the working tree, you\n+\tshould tell Git where the top-level of the working tree is,\n+\twith the --work-tree= option (or GIT_WORK_TREE\n+\tenvironment variable)\n+\n+\tIf you just want to run git as if it was started in then use\n+\tgit -C.\n \n --work-tree=::\n \tSet the path to the working tree. It can be an absolute path\n\nbase-commit: 232378479ee6c66206d47a9be175e3a39682aea6\n-- \ngitgitgadget\n"},{"id":"390532","messageId":"b494114d-02ef-599f-4fa0-d7614974a130@kdbg.org","threadId":"52681","inReplyTo":"pull.537.v2.git.1580091855792.gitgitgadget@gmail.com","subject":"Re: [PATCH v2] git: update documentation for --git-dir","fromName":"Johannes Sixt","fromEmail":"j6t@kdbg.org","sentAt":"2020-01-27T06:28:58Z","receivedAt":"2020-01-27T06:29:04Z","isPatch":true,"sender":{"key":"j6t@kdbg.org","avatar":"https://avatars.githubusercontent.com/u/14810926?v=4"},"body":"Am 27.01.20 um 03:24 schrieb Heba Waly via GitGitGadget:\n> diff --git a/Documentation/git.txt b/Documentation/git.txt\n> index b1597ac002..cf73f501b6 100644\n> --- a/Documentation/git.txt\n> +++ b/Documentation/git.txt\n> @@ -110,9 +110,23 @@ foo.bar= ...`) sets `foo.bar` to the empty string which `git config\n> \tDo not pipe Git output into a pager.\n> \n> --git-dir=::\n> -\tSet the path to the repository. This can also be controlled by\n> -\tsetting the `GIT_DIR` environment variable. It can be an absolute\n> -\tpath or relative path to current working directory.\n> +\tSet the path to the repository (\".git\" directory). This can also be\n> +\tcontrolled by setting the `GIT_DIR` environment variable. It can be\n> +\tan absolute path or relative path to current working directory.\n> +\n> +\tSpecifying the location of the \".git\" directory using this\n> +\toption (or GIT_DIR environment variable) turns off the\n> +\trepository discovery that tries to find a directory with\n> +\t\".git\" subdirectory (which is how the repository and the\n> +\ttop-level of the working tree are discovered), and tells Git\n> +\tthat you are at the top level of the working tree. If you\n> +\tare not at the top-level directory of the working tree, you\n> +\tshould tell Git where the top-level of the working tree is,\n> +\twith the --work-tree= option (or GIT_WORK_TREE\n> +\tenvironment variable)\n> +\n> +\tIf you just want to run git as if it was started in then use\n> +\tgit -C.\n\nDoes this render well? Judging by the precedent set by the descriptions\nof -C and -c options earlier in this file, continuation paragraphs\nshould not be indented and separated by a line with just a plus sign\ninstead of an empty line.\n\n-- Hannes\n"},{"id":"390608","messageId":"CACg5j24TNczbZZ3u0UR_MYQgeWk8HRY-cxc3N8HX=v-Tx0vi3A@mail.gmail.com","threadId":"52681","inReplyTo":"b494114d-02ef-599f-4fa0-d7614974a130@kdbg.org","subject":"Re: [PATCH v2] git: update documentation for --git-dir","fromName":"Heba Waly","fromEmail":"heba.waly@gmail.com","sentAt":"2020-01-28T04:17:49Z","receivedAt":"2020-01-28T04:18:04Z","isPatch":true,"sender":{"key":"heba.waly@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1539076?v=4"},"body":"On Mon, Jan 27, 2020 at 7:29 PM Johannes Sixt wrote:\n>\n> Does this render well? Judging by the precedent set by the descriptions\n> of -C and -c options earlier in this file, continuation paragraphs\n> should not be indented and separated by a line with just a plus sign\n> instead of an empty line.\n\nIt doesn't render well, thanks for pointing it out, will send an\nupdated version.\n\nThanks,\nHeba\n"},{"id":"390609","messageId":"pull.537.v3.git.1580185440512.gitgitgadget@gmail.com","threadId":"52681","inReplyTo":"pull.537.v2.git.1580091855792.gitgitgadget@gmail.com","subject":"[PATCH v3] git: update documentation for --git-dir","fromName":"Heba Waly via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2020-01-28T04:24:00Z","receivedAt":"2020-01-28T04:24:05Z","isPatch":true,"sender":{"key":"heba.waly@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1539076?v=4"},"body":"From: Heba Waly \n\ngit --git-dir is a bit confusing and sometimes doesn't work as\nthe user would expect it to.\n\nFor example, if the user runs `git --git-dir= status`, git\nwill skip the repository discovery algorithm and will assign the\nwork tree to the user's current work directory unless otherwise\nspecified. When this assignment is wrong, the output will not match\nthe user's expectations.\n\nThis patch updates the documentation to make it clearer.\n\nSigned-off-by: Heba Waly \nHelped-by: Junio C Hamano \n---\n [Outreachy] git: update documentation for --git-dir\n \n git --git-dir is a bit confusing and sometimes doesn't work as the user\n would expect it to.\n \n For example, if the user runs git --git-dir= status, git will not\n be able to figure out the work tree path on its own and will assign the\n work tree to the user's current work directory. When this assignment is\n wrong, then the output will not match the user's expectations.\n \n This patch updates the documentation to make it clearer.\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-537%2FHebaWaly%2Fgit_dir_doc-v3\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-537/HebaWaly/git_dir_doc-v3\nPull-Request: https://github.com/gitgitgadget/git/pull/537\n\nRange-diff vs v2:\n\n 1: 8a69eecb97 ! 1: 2a1404f1b3 git: update documentation for --git-dir\n @@ -29,20 +29,20 @@\n +\tSet the path to the repository (\".git\" directory). This can also be\n +\tcontrolled by setting the `GIT_DIR` environment variable. It can be\n +\tan absolute path or relative path to current working directory.\n -+\n -+\tSpecifying the location of the \".git\" directory using this\n -+\toption (or GIT_DIR environment variable) turns off the\n -+\trepository discovery that tries to find a directory with\n -+\t\".git\" subdirectory (which is how the repository and the\n -+\ttop-level of the working tree are discovered), and tells Git\n -+\tthat you are at the top level of the working tree. If you\n -+\tare not at the top-level directory of the working tree, you\n -+\tshould tell Git where the top-level of the working tree is,\n -+\twith the --work-tree= option (or GIT_WORK_TREE\n -+\tenvironment variable)\n -+\n -+\tIf you just want to run git as if it was started in then use\n -+\tgit -C.\n +++\n ++Specifying the location of the \".git\" directory using this\n ++option (or GIT_DIR environment variable) turns off the\n ++repository discovery that tries to find a directory with\n ++\".git\" subdirectory (which is how the repository and the\n ++top-level of the working tree are discovered), and tells Git\n ++that you are at the top level of the working tree. If you\n ++are not at the top-level directory of the working tree, you\n ++should tell Git where the top-level of the working tree is,\n ++with the --work-tree= option (or GIT_WORK_TREE\n ++environment variable)\n +++\n ++If you just want to run git as if it was started in then use\n ++git -C.\n \n --work-tree=::\n \tSet the path to the working tree. It can be an absolute path\n\n\n Documentation/git.txt | 20 +++++++++++++++++---\n 1 file changed, 17 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex b1597ac002..c21e33aa10 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -110,9 +110,23 @@ foo.bar= ...`) sets `foo.bar` to the empty string which `git config\n \tDo not pipe Git output into a pager.\n \n --git-dir=::\n-\tSet the path to the repository. This can also be controlled by\n-\tsetting the `GIT_DIR` environment variable. It can be an absolute\n-\tpath or relative path to current working directory.\n+\tSet the path to the repository (\".git\" directory). This can also be\n+\tcontrolled by setting the `GIT_DIR` environment variable. It can be\n+\tan absolute path or relative path to current working directory.\n++\n+Specifying the location of the \".git\" directory using this\n+option (or GIT_DIR environment variable) turns off the\n+repository discovery that tries to find a directory with\n+\".git\" subdirectory (which is how the repository and the\n+top-level of the working tree are discovered), and tells Git\n+that you are at the top level of the working tree. If you\n+are not at the top-level directory of the working tree, you\n+should tell Git where the top-level of the working tree is,\n+with the --work-tree= option (or GIT_WORK_TREE\n+environment variable)\n++\n+If you just want to run git as if it was started in then use\n+git -C.\n \n --work-tree=::\n \tSet the path to the working tree. It can be an absolute path\n\nbase-commit: 232378479ee6c66206d47a9be175e3a39682aea6\n-- \ngitgitgadget\n"},{"id":"390613","messageId":"20200128073340.GA564804@coredump.intra.peff.net","threadId":"52681","inReplyTo":"CACg5j24TNczbZZ3u0UR_MYQgeWk8HRY-cxc3N8HX=v-Tx0vi3A@mail.gmail.com","subject":"Re: [PATCH v2] git: update documentation for --git-dir","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2020-01-28T07:33:40Z","receivedAt":"2020-01-28T07:33:43Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Jan 28, 2020 at 05:17:49PM +1300, Heba Waly wrote:\n\n> On Mon, Jan 27, 2020 at 7:29 PM Johannes Sixt wrote:\n> >\n> > Does this render well? Judging by the precedent set by the descriptions\n> > of -C and -c options earlier in this file, continuation paragraphs\n> > should not be indented and separated by a line with just a plus sign\n> > instead of an empty line.\n> \n> It doesn't render well, thanks for pointing it out, will send an\n> updated version.\n\nOne tool that might help as you do documentation patches: there's a\ndoc-diff script that shows the rendered differences.\n\nTry:\n\n cd Documentation\n ./doc-diff HEAD^ HEAD\n\n(on a branch with your patch at the tip). It was originally written to\ninvestigate changes to the markup, etc, but I find it's useful just for\nlooking at any documentation patch, because it takes you right to the\npart that changed. :)\n\n-Peff\n"},{"id":"390620","messageId":"CACg5j27fEEwL0yHhYcX=UB-W-iWkd587OCkSE1vvbcfSurxGXA@mail.gmail.com","threadId":"52681","inReplyTo":"20200128073340.GA564804@coredump.intra.peff.net","subject":"Re: [PATCH v2] git: update documentation for --git-dir","fromName":"Heba Waly","fromEmail":"heba.waly@gmail.com","sentAt":"2020-01-28T10:40:50Z","receivedAt":"2020-01-28T10:41:05Z","isPatch":true,"sender":{"key":"heba.waly@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1539076?v=4"},"body":"On Tue, Jan 28, 2020 at 8:33 PM Jeff King wrote:\n>\n> One tool that might help as you do documentation patches: there's a\n> doc-diff script that shows the rendered differences.\n>\n> Try:\n>\n> cd Documentation\n> ./doc-diff HEAD^ HEAD\n>\n> (on a branch with your patch at the tip). It was originally written to\n> investigate changes to the markup, etc, but I find it's useful just for\n> looking at any documentation patch, because it takes you right to the\n> part that changed. :)\n>\n\nNice, thank you for the tip :)\n\nHeba\n"},{"id":"390662","messageId":"xmqq7e1b8jyq.fsf@gitster-ct.c.googlers.com","threadId":"52681","inReplyTo":"pull.537.v3.git.1580185440512.gitgitgadget@gmail.com","subject":"Re: [PATCH v3] git: update documentation for --git-dir","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-01-28T19:22:21Z","receivedAt":"2020-01-28T19:22:28Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Heba Waly via GitGitGadget\" writes:\n\n> --git-dir=::\n> -\tSet the path to the repository. This can also be controlled by\n> -\tsetting the `GIT_DIR` environment variable. It can be an absolute\n> -\tpath or relative path to current working directory.\n> +\tSet the path to the repository (\".git\" directory). This can also be\n> +\tcontrolled by setting the `GIT_DIR` environment variable. It can be\n> +\tan absolute path or relative path to current working directory.\n> ++\n> +Specifying the location of the \".git\" directory using this\n> +option (or GIT_DIR environment variable) turns off the\n\nConsistently quote, like `GIT_DIR`, here?\n\n> +repository discovery that tries to find a directory with\n> +\".git\" subdirectory (which is how the repository and the\n> +top-level of the working tree are discovered), and tells Git\n> +that you are at the top level of the working tree. If you\n> +are not at the top-level directory of the working tree, you\n> +should tell Git where the top-level of the working tree is,\n> +with the --work-tree= option (or GIT_WORK_TREE\n\nLikewise. We may probably want to say `--work-tree=` inside a\nbq pair, and definitely `GIT_WORK_TREE` inside a bq pair.\n\n> +environment variable)\n> ++\n> +If you just want to run git as if it was started in then use\n> +git -C.\n\nThis is the best part of this patch, I would think. But you said\n in the \"if\" part of this \"if--then\", so (unless your Git\nmagically can read users' minds some magic), I'd expect to see the\nsame to appear somewhere in the \"then\" part.\n\n\tIf you just want to run git as if it was started in ``\n\tthen use `git -C `.\n\nperhaps?\n"},{"id":"390721","messageId":"CACg5j26EEMYkbp4F0AoVSKE5BWwYXvxRqJSovRdzNitqbHzzqQ@mail.gmail.com","threadId":"52681","inReplyTo":"xmqq7e1b8jyq.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH v3] git: update documentation for --git-dir","fromName":"Heba Waly","fromEmail":"heba.waly@gmail.com","sentAt":"2020-01-29T12:10:03Z","receivedAt":"2020-01-29T12:10:18Z","isPatch":true,"sender":{"key":"heba.waly@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1539076?v=4"},"body":"On Wed, Jan 29, 2020 at 8:22 AM Junio C Hamano wrote:\n>\n> \"Heba Waly via GitGitGadget\" writes:\n>\n> > --git-dir=::\n> > - Set the path to the repository. This can also be controlled by\n> > - setting the `GIT_DIR` environment variable. It can be an absolute\n> > - path or relative path to current working directory.\n> > + Set the path to the repository (\".git\" directory). This can also be\n> > + controlled by setting the `GIT_DIR` environment variable. It can be\n> > + an absolute path or relative path to current working directory.\n> > ++\n> > +Specifying the location of the \".git\" directory using this\n> > +option (or GIT_DIR environment variable) turns off the\n>\n> Consistently quote, like `GIT_DIR`, here?\n>\n\nOk\n\n> > +repository discovery that tries to find a directory with\n> > +\".git\" subdirectory (which is how the repository and the\n> > +top-level of the working tree are discovered), and tells Git\n> > +that you are at the top level of the working tree. If you\n> > +are not at the top-level directory of the working tree, you\n> > +should tell Git where the top-level of the working tree is,\n> > +with the --work-tree= option (or GIT_WORK_TREE\n>\n> Likewise. We may probably want to say `--work-tree=` inside a\n> bq pair, and definitely `GIT_WORK_TREE` inside a bq pair.\n>\n\nOk\n\n> > +environment variable)\n> > ++\n> > +If you just want to run git as if it was started in then use\n> > +git -C.\n>\n> This is the best part of this patch, I would think. But you said\n> in the \"if\" part of this \"if--then\", so (unless your Git\n> magically can read users' minds some magic), I'd expect to see the\n> same to appear somewhere in the \"then\" part.\n>\n\nBy here I'm referring to the path parameter of git --git-dir=.\nAnd by mentioning `git -C` without any parameters, my intention is to point the\nuser to scroll up and read about git -C and its parameters. Given that was\nconfusing to you, I don't mind stating the command in its simplest form as\nyou suggested: `git -C `\n\n> If you just want to run git as if it was started in ``\n> then use `git -C `.\n>\n> perhaps?\n\nThanks,\nHeba\n"},{"id":"390761","messageId":"pull.537.v4.git.1580346841614.gitgitgadget@gmail.com","threadId":"52681","inReplyTo":"pull.537.v3.git.1580185440512.gitgitgadget@gmail.com","subject":"[PATCH v4] git: update documentation for --git-dir","fromName":"Heba Waly via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2020-01-30T01:14:01Z","receivedAt":"2020-01-30T01:14:08Z","isPatch":true,"sender":{"key":"heba.waly@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1539076?v=4"},"body":"From: Heba Waly \n\ngit --git-dir is a bit confusing and sometimes doesn't work as\nthe user would expect it to.\n\nFor example, if the user runs `git --git-dir= status`, git\nwill skip the repository discovery algorithm and will assign the\nwork tree to the user's current work directory unless otherwise\nspecified. When this assignment is wrong, the output will not match\nthe user's expectations.\n\nThis patch updates the documentation to make it clearer.\n\nSigned-off-by: Heba Waly \nHelped-by: Junio C Hamano \n---\n [Outreachy] git: update documentation for --git-dir\n \n git --git-dir is a bit confusing and sometimes doesn't work as the user\n would expect it to.\n \n For example, if the user runs git --git-dir= status, git will skip\n the repository discovery algorithm and will assign the work tree to the\n user's current work directory unless otherwise specified. When this\n assignment is wrong, the output will not match the user's expectations.\n \n This patch updates the documentation to make it clearer.\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-537%2FHebaWaly%2Fgit_dir_doc-v4\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-537/HebaWaly/git_dir_doc-v4\nPull-Request: https://github.com/gitgitgadget/git/pull/537\n\nRange-diff vs v3:\n\n 1: 2a1404f1b3 ! 1: e27f150c4b git: update documentation for --git-dir\n @@ -31,18 +31,18 @@\n +\tan absolute path or relative path to current working directory.\n ++\n +Specifying the location of the \".git\" directory using this\n -+option (or GIT_DIR environment variable) turns off the\n ++option (or `GIT_DIR` environment variable) turns off the\n +repository discovery that tries to find a directory with\n +\".git\" subdirectory (which is how the repository and the\n +top-level of the working tree are discovered), and tells Git\n +that you are at the top level of the working tree. If you\n +are not at the top-level directory of the working tree, you\n +should tell Git where the top-level of the working tree is,\n -+with the --work-tree= option (or GIT_WORK_TREE\n ++with the `--work-tree=` option (or `GIT_WORK_TREE`\n +environment variable)\n ++\n -+If you just want to run git as if it was started in then use\n -+git -C.\n ++If you just want to run git as if it was started in `` then use\n ++`git -C `.\n \n --work-tree=::\n \tSet the path to the working tree. It can be an absolute path\n\n\n Documentation/git.txt | 20 +++++++++++++++++---\n 1 file changed, 17 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex b1597ac002..41374f24fa 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -110,9 +110,23 @@ foo.bar= ...`) sets `foo.bar` to the empty string which `git config\n \tDo not pipe Git output into a pager.\n \n --git-dir=::\n-\tSet the path to the repository. This can also be controlled by\n-\tsetting the `GIT_DIR` environment variable. It can be an absolute\n-\tpath or relative path to current working directory.\n+\tSet the path to the repository (\".git\" directory). This can also be\n+\tcontrolled by setting the `GIT_DIR` environment variable. It can be\n+\tan absolute path or relative path to current working directory.\n++\n+Specifying the location of the \".git\" directory using this\n+option (or `GIT_DIR` environment variable) turns off the\n+repository discovery that tries to find a directory with\n+\".git\" subdirectory (which is how the repository and the\n+top-level of the working tree are discovered), and tells Git\n+that you are at the top level of the working tree. If you\n+are not at the top-level directory of the working tree, you\n+should tell Git where the top-level of the working tree is,\n+with the `--work-tree=` option (or `GIT_WORK_TREE`\n+environment variable)\n++\n+If you just want to run git as if it was started in `` then use\n+`git -C `.\n \n --work-tree=::\n \tSet the path to the working tree. It can be an absolute path\n\nbase-commit: 232378479ee6c66206d47a9be175e3a39682aea6\n-- \ngitgitgadget\n"},{"id":"390825","messageId":"xmqqr1zgdcmq.fsf@gitster-ct.c.googlers.com","threadId":"52681","inReplyTo":"pull.537.v4.git.1580346841614.gitgitgadget@gmail.com","subject":"Re: [PATCH v4] git: update documentation for --git-dir","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-01-30T18:26:21Z","receivedAt":"2020-01-30T18:26:26Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Heba Waly via GitGitGadget\" writes:\n\n> Range-diff vs v3:\n>\n> 1: 2a1404f1b3 ! 1: e27f150c4b git: update documentation for --git-dir\n> @@ -31,18 +31,18 @@\n> +\tan absolute path or relative path to current working directory.\n> ++\n> +Specifying the location of the \".git\" directory using this\n> -+option (or GIT_DIR environment variable) turns off the\n> ++option (or `GIT_DIR` environment variable) turns off the\n> +repository discovery that tries to find a directory with\n> +\".git\" subdirectory (which is how the repository and the\n> +top-level of the working tree are discovered), and tells Git\n> +that you are at the top level of the working tree. If you\n> +are not at the top-level directory of the working tree, you\n> +should tell Git where the top-level of the working tree is,\n> -+with the --work-tree= option (or GIT_WORK_TREE\n> ++with the `--work-tree=` option (or `GIT_WORK_TREE`\n> +environment variable)\n> ++\n> -+If you just want to run git as if it was started in then use\n> -+git -C.\n> ++If you just want to run git as if it was started in `` then use\n> ++`git -C `.\n\nWill replace and queue. Thanks. \n"}]}