# [PATCH] gitcli: tweak "man gitcli" for clarity 3 messages from 2017-11-21 to 2017-11-21. Participants: Robert P. J. Day, Eric Sunshine. Thread: https://gitlist.dev/t/47278 ## Robert P. J. Day, 2017-11-21 20:53 Subject: [PATCH] gitcli: tweak "man gitcli" for clarity Message-ID: URL: https://gitlist.dev/e/alpine.LFD.2.21.1711211551230.24935%40localhost.localdomain ``` No major changes, just some rewording and showing some variations of general Git commands. Signed-off-by: Robert P. J. Day --- diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index 9f13266a6..a4efcb7ce 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -13,7 +13,7 @@ gitcli DESCRIPTION ----------- -This manual describes the convention used throughout Git CLI. +This manual describes the common conventions used throughout Git CLI. Many commands take revisions (most often "commits", but sometimes "tree-ish", depending on the context and command) and paths as their @@ -32,32 +32,35 @@ arguments. Here are the rules: between the HEAD commit and the work tree as a whole". You can say `git diff HEAD --` to ask for the latter. - * Without disambiguating `--`, Git makes a reasonable guess, but errors - out and asking you to disambiguate when ambiguous. E.g. if you have a + * Without a disambiguating `--`, Git makes a reasonable guess, but can + error out, asking you to disambiguate when ambiguous. E.g. if you have a file called HEAD in your work tree, `git diff HEAD` is ambiguous, and you have to say either `git diff HEAD --` or `git diff -- HEAD` to disambiguate. + When writing a script that is expected to handle random user-input, it is a good practice to make it explicit which arguments are which by placing -disambiguating `--` at appropriate places. +a disambiguating `--` at appropriate places. * Many commands allow wildcards in paths, but you need to protect - them from getting globbed by the shell. These two mean different - things: + them from getting globbed by the shell. The following commands have + two different meanings: + -------------------------------- $ git checkout -- *.c + $ git checkout -- \*.c +$ git checkout -- "*.c" +$ git checkout -- '*.c' -------------------------------- + -The former lets your shell expand the fileglob, and you are asking -the dot-C files in your working tree to be overwritten with the version -in the index. The latter passes the `*.c` to Git, and you are asking -the paths in the index that match the pattern to be checked out to your -working tree. After running `git add hello.c; rm hello.c`, you will _not_ -see `hello.c` in your working tree with the former, but with the latter -you will. +The first command lets your shell expand the fileglob, and you are asking +the dot-C files in your working tree to be overwritten with the version in +the index. The latter three variations pass the `*.c` to Git, and you are +asking the paths in the index that match the pattern to be checked out to +your working tree. After running `git add hello.c; rm hello.c`, you will +_not_ see `hello.c` in your working tree with the first command, but with +the latter three variations, you will. * Just as the filesystem '.' (period) refers to the current directory, using a '.' as a repository name in Git (a dot-repository) is a relative -- ======================================================================== Robert P. J. Day Ottawa, Ontario, CANADA http://crashcourse.ca Twitter: http://twitter.com/rpjday LinkedIn: http://ca.linkedin.com/in/rpjday ======================================================================== ``` ## Eric Sunshine, 2017-11-21 21:24 Subject: Re: [PATCH] gitcli: tweak "man gitcli" for clarity Message-ID: URL: https://gitlist.dev/e/CAPig%2BcS2i1WOYg1d3fup0PPq_HzJE_XXXtkEMqxq%3D1Fc9E1sMQ%40mail.gmail.com In-Reply-To: ``` On Tue, Nov 21, 2017 at 3:53 PM, Robert P. J. Day wrote: > No major changes, just some rewording and showing some variations of > general Git commands. > > Signed-off-by: Robert P. J. Day > --- > diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt > @@ -13,7 +13,7 @@ gitcli > DESCRIPTION > ----------- > > -This manual describes the convention used throughout Git CLI. > +This manual describes the common conventions used throughout Git CLI. The Department of Redundancy department... ``` ## Robert P. J. Day, 2017-11-21 21:25 Subject: Re: [PATCH] gitcli: tweak "man gitcli" for clarity Message-ID: URL: https://gitlist.dev/e/alpine.LFD.2.21.1711211624560.26021%40localhost.localdomain In-Reply-To: ``` On Tue, 21 Nov 2017, Eric Sunshine wrote: > On Tue, Nov 21, 2017 at 3:53 PM, Robert P. J. Day wrote: > > No major changes, just some rewording and showing some variations of > > general Git commands. > > > > Signed-off-by: Robert P. J. Day > > --- > > diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt > > @@ -13,7 +13,7 @@ gitcli > > DESCRIPTION > > ----------- > > > > -This manual describes the convention used throughout Git CLI. > > +This manual describes the common conventions used throughout Git CLI. > > The Department of Redundancy department... oh, fine, reduced redundancy coming shortly ... rday -- ======================================================================== Robert P. J. Day Ottawa, Ontario, CANADA http://crashcourse.ca Twitter: http://twitter.com/rpjday LinkedIn: http://ca.linkedin.com/in/rpjday ======================================================================== ```