git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [PATCH 25/25] list-files: documentation

From
Eric Sunshine <sunshine@sunshineco.com>
Date
Apr 6, 2015, 21:37 UTC
Message-ID
<CAPig+cR+-j6HJffMjhWiVjd1tVKaQKe9-dgJMtOcB_7AeKE9UQ@mail.gmail.com>
In-Reply-To
<1428328354-14897-26-git-send-email-pclouds@gmail.com>
On Mon, Apr 6, 2015 at 9:52 AM, Nguyễn Thái Ngọc Duy <pclouds@gmail.com> wrote:
Show 32 quoted lines
> Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
> ---
> diff --git a/Documentation/git-list-files.txt b/Documentation/git-list-files.txt
> new file mode 100644
> index 0000000..9b9edce
> --- /dev/null
> +++ b/Documentation/git-list-files.txt
> @@ -0,0 +1,115 @@
> +git-list-files(1)
> +===============
> +
> +NAME
> +----
> +git-list-files - List files
> +
> +SYNOPSIS
> +--------
> +[verse]
> +'git list-files [options] [<pathspec>...]
> +
> +DESCRIPTION
> +-----------
> +List files (by default in current working directory) that are in the
> +index. Depending on the chosen options, maybe only modified files in
> +working tree are shown, or untracked files... The builtin alias "ls"
> +is set to "list-files".
> +
> +OPTIONS
> +-------
> +-c::
> +--cached::
> +       Show cached files (default)
Here and elsewhere: s/$/./
Show 12 quoted lines
> +-d::
> +--deleted::
> +       Show deleted files in index, compared to HEAD
> +
> +-a::
> +--added::
> +       Show added files in index, compared to HEAD
> +
> +-m::
> +--modified::
> +       Show modified files in index, compared to HEAD. This implies
> +       --deleted and --added

s/--deleted/`--deleted`/ s/--added/`--added`/

Show 12 quoted lines
> +-D::
> +--wt-deleted::
> +       Show deleted files in working directory
> +
> +-A::
> +--wt-added::
> +       Show added files in working directory
> +
> +-M::
> +--wt-modified::
> +       Show modified files in working directory. This implies
> +       --wt-deleted and --wt-added

s/--wt-deleted/`--wt-deleted`/ s/--wt-added/`--wt-added`/

> +-o::
> +--others::
> +       Show untracked files (and only unignored ones unless -i is
s/-i/`-i`/ ...or... s/-i/`--ignored`/
Show 24 quoted lines
> +       specified)
> +
> +-i::
> +--ignored::
> +       Show only ignored files. When showing files in the index,
> +       print only those matched by an exclude pattern. When showing
> +       "other" files, show only those matched by an exclude pattern.
> +
> +-u::
> +--unmerged::
> +       Show unmerged files
> +
> +-F::
> +--classify::
> +       Append indicator (one of `*/=>@|&`, which is executable,
> +       directory, socket, Solaris door, symlink, fifo, or submodule
> +       respectively) to entries.
> +
> +--color[=<when>]::
> +--no-color::
> +       Color file names. The value must be `always`, `never`, or
> +       `auto`. `--no-color` is equivalent to
> +       `--color=never`. `--color` is equivalent to
> +       `--color=auto`. See configuration variable `color.list-files`
Is 'color.list-files' documented anywhere?
Show 6 quoted lines
> +       for the default settings.
> +
> +--column[=<options>]::
> +--no-column::
> +-1::
> +       Display files in columns. See configuration variable column.ui
s/column.ui/`column.ui`/
> +       for option syntax. `--column` and `--no-column` without options
> +       are equivalent to 'always' and 'never' respectively.
> +       `-1` is a shortcut for --no-column.
s/--no-column/`--no-column`/
Show 8 quoted lines
> +--max-depth=<depth>::
> +--recursive::
> +-R::
> +       For each <pathspec> given on command line, descend at most <depth>
> +       levels of directories. A negative value means no limit.
> +       This option is ignored if <pathspec> contains active wildcards.
> +       In other words if "a*" matches a directory named "a*",
> +       "*" is matched literally so --max-depth is still effective.
s/--max-depth/`--max-depth`/
Show 8 quoted lines
> +       `-R` or `--recursive` is equivalent of `--max-depth=-1`
> +       (infinite recursion).  The default is `--max-depth=0`.
> +
> +--tag::
> +--no-tag::
> +       Usually when tags are displayed by the left of the file name if
> +       there are more than one file selection. Use either of these options
> +       to force always or never display tags.

This is somewhat difficult to parse. Perhaps it could be rephrased something like this:

    If the disposition of listed files differs from one another, then
    tags ("D" deleted, "M" modified, etc.) are displayed in front of
    the file names; otherwise tags are suppressed. These options
    override the the behavior and explicitly show or suppress tags,
    respectively.
Show 13 quoted lines
> +
> +<pathspec>::
> +       Files to show. :(glob) magic is enabled by default.
> +
> +SEE ALSO
> +--------
> +linkgit:git-ls-files[1]
> +
> +GIT
> +---
> +Part of the linkgit:git[1] suite
> --
> 2.3.0.rc1.137.g477eb31
Previous: Nguyễn Thái Ngọc DuyNext: Duy Nguyen
Message 35 of 36 in “list-files redesign”
  1. 00/25 list-files redesignNguyễn Thái Ngọc Duy, Apr 6, 2015
  2. 01/25 ls_colors.c: add $LS_COLORS parsing codeNguyễn Thái Ngọc Duy, Apr 6, 2015
  3. 02/25 ls_colors.c: parse color.ls.* from config fileNguyễn Thái Ngọc Duy, Apr 6, 2015
  4. 03/25 ls_colors.c: add a function to color a file nameNguyễn Thái Ngọc Duy, Apr 6, 2015
  5. 04/25 ls_colors.c: highlight submodules like directoriesNguyễn Thái Ngọc Duy, Apr 6, 2015
  6. 05/25 list-files: command skeletonNguyễn Thái Ngọc Duy, Apr 6, 2015
  7. 06/25 list-files: show paths relative to cwdNguyễn Thái Ngọc Duy, Apr 6, 2015
  8. 07/25 list-files: add tag to each entry, filter duplicate tagsNguyễn Thái Ngọc Duy, Apr 6, 2015
  9. Eric SunshineApr 6, 2015
  10. 08/25 list-files: add --[no-]column, -C and -1Nguyễn Thái Ngọc Duy, Apr 6, 2015
  11. 09/25 list-files: add --max-depth, -R and default to --max-depth=0Nguyễn Thái Ngọc Duy, Apr 6, 2015
  12. 10/25 list-files: show directories as well as filesNguyễn Thái Ngọc Duy, Apr 6, 2015
  13. 11/25 list-files: add --colorNguyễn Thái Ngọc Duy, Apr 6, 2015
  14. Eric SunshineApr 6, 2015
  15. 12/25 list-files: add -F/--classifyNguyễn Thái Ngọc Duy, Apr 6, 2015
  16. 13/25 list-files: new indicator '&' for submodules when -F is usedNguyễn Thái Ngọc Duy, Apr 6, 2015
  17. 14/25 list-files: add --cached and --othersNguyễn Thái Ngọc Duy, Apr 6, 2015
  18. 15/25 list-files: add --ignoredNguyễn Thái Ngọc Duy, Apr 6, 2015
  19. Eric SunshineApr 6, 2015
  20. 16/25 list-files: add --unmergedNguyễn Thái Ngọc Duy, Apr 6, 2015
  21. Eric SunshineApr 6, 2015
  22. 17/25 list-files: add file modification options -[admADM]Nguyễn Thái Ngọc Duy, Apr 6, 2015
  23. Eric SunshineApr 6, 2015
  24. 18/25 list-files: delete redundant cached entriesNguyễn Thái Ngọc Duy, Apr 6, 2015
  25. Eric SunshineApr 6, 2015
  26. Junio C HamanoApr 8, 2015
  27. 19/25 list-files: make alias 'ls' default to 'list-files'Nguyễn Thái Ngọc Duy, Apr 6, 2015
  28. 20/25 list-files: preload indexNguyễn Thái Ngọc Duy, Apr 6, 2015
  29. Eric SunshineApr 6, 2015
  30. 21/25 list-files: reduce match_pathspec calls in matched()Nguyễn Thái Ngọc Duy, Apr 6, 2015
  31. 22/25 list-files: only do diff that is actually usefulNguyễn Thái Ngọc Duy, Apr 6, 2015
  32. 23/25 pathspec: move getenv() code out of prefix_pathspec()Nguyễn Thái Ngọc Duy, Apr 6, 2015
  33. 24/25 list-files: make :(glob) pathspec defaultNguyễn Thái Ngọc Duy, Apr 6, 2015
  34. 25/25 list-files: documentationNguyễn Thái Ngọc Duy, Apr 6, 2015
  35. Eric SunshineApr 6, 2015
  36. Duy NguyenApr 6, 2015

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.