{"thread":{"id":"49536","subject":"Bug: manpage for `git ls-files` uses <file> instead of <pathspec>","startedAt":"2018-10-11T03:20:04Z","lastAt":"2018-10-13T08:03:18Z","messageCount":2,"participants":["Lily Ballard","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"360136","messageId":"1539228001.1758106.1538051752.20CB6C51@webmail.messagingengine.com","threadId":"49536","inReplyTo":null,"subject":"Bug: manpage for `git ls-files` uses <file> instead of <pathspec>","fromName":"Lily Ballard","fromEmail":"lily@sb.org","sentAt":"2018-10-11T03:20:01Z","receivedAt":"2018-10-11T03:20:04Z","isPatch":false,"sender":{"key":"lily@sb.org","avatar":null},"body":"`git ls-files` takes zero or more <pathspec>s, but the manpage (and the `-h` output) lists it as taking zero or more <file>s instead. This is confusing as <file> is documented in `man git` as a filename, without any magic. But a pathspec has a lot of special handling. The gitglossary entry for pathspec does say that `git ls-files` takes it, but nobody is going to know to look there in the first place if they look at `git ls-files` and see that it takes files. \n\nI haven’t checked any other commands that the glossary lists as taking pathspecs (except `git add`, which does properly list it as taking pathspecs), so I don’t know if any of the other commands incorrectly list themselves as taking files when they take pathspecs.\n\ngit version 2.19.1.\n\n-Lily Ballard\n"},{"id":"360382","messageId":"xmqqzhvi8e9r.fsf@gitster-ct.c.googlers.com","threadId":"49536","inReplyTo":"1539228001.1758106.1538051752.20CB6C51@webmail.messagingengine.com","subject":"Re: Bug: manpage for `git ls-files` uses <file> instead of <pathspec>","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2018-10-13T08:03:12Z","receivedAt":"2018-10-13T08:03:18Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Lily Ballard <lily@sb.org> writes:\n\n> I haven’t checked any other commands that the glossary lists as\n> taking pathspecs (except `git add`, which does properly list it as\n> taking pathspecs), so I don’t know if any of the other commands\n> incorrectly list themselves as taking files when they take\n> pathspecs.\n\nI do not offhand think of a command that only takes pathname,\nincluding \"ls-files\".  New users would think \"git cmd README\" is\ntaking a single filename \"README\", and \"ls-files\" doc uses \"file\"\nin a misguided attempt to be \"newbie friendly\", but it always has\nused that \"README\" string as a pattern to match paths against.\n"}]}