Really honour NO_PYTHON

[git.git] / Documentation / git-ls-files.txt

diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 7ac6c7d..fe53412 100644 (file)
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -1,20 +1,20 @@
 git-ls-files(1)
 ===============
 git-ls-files(1)
 ===============

-v0.1, May 2005

 
 NAME
 ----
 
 NAME
 ----

-git-ls-files - Information about files in the cache/working directory
+git-ls-files - Information about files in the index/working directory

 
 
 SYNOPSIS
 --------
 'git-ls-files' [-z] [-t]
 
 
 SYNOPSIS
 --------
 'git-ls-files' [-z] [-t]

-               (--[cached|deleted|others|ignored|stage|unmerged|killed])\*
-               (-[c|d|o|i|s|u|k])\*
+               (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])\*
+               (-[c|d|o|i|s|u|k|m])\*

                [-x <pattern>|--exclude=<pattern>]
                [-X <file>|--exclude-from=<file>]
                [-x <pattern>|--exclude=<pattern>]
                [-X <file>|--exclude-from=<file>]

-               [--exclude-per-directory=<file>]
+               [--exclude-per-directory=<file>] 
+               [--full-name] [--] [<file>]\*

 
 DESCRIPTION
 -----------
 
 DESCRIPTION
 -----------


@@ -33,6 +33,9 @@ OPTIONS
 -d|--deleted::
        Show deleted files in the output
 
 -d|--deleted::
        Show deleted files in the output
 

+-m|--modified::
+       Show modified files in the output
+

 -o|--others::
        Show other files in the output
 
 -o|--others::
        Show other files in the output
 


@@ -43,16 +46,20 @@ OPTIONS
 -s|--stage::
        Show stage files in the output
 
 -s|--stage::
        Show stage files in the output
 

+--directory::
+       If a whole directory is classified as "other", show just its
+       name (with a trailing slash) and not its whole contents.
+

 -u|--unmerged::
        Show unmerged files in the output (forces --stage)
 
 -k|--killed::
        Show files on the filesystem that need to be removed due
 -u|--unmerged::
        Show unmerged files in the output (forces --stage)
 
 -k|--killed::
        Show files on the filesystem that need to be removed due

-       to file/directory conflicts for checkout-cache to
+       to file/directory conflicts for checkout-index to

        succeed.
 
 -z::
        succeed.
 
 -z::

-       \0 line termination on output
+       \0 line termination on output.

 
 -x|--exclude=<pattern>::
        Skips files matching pattern.
 
 -x|--exclude=<pattern>::
        Skips files matching pattern.


@@ -68,11 +75,25 @@ OPTIONS
 -t::
        Identify the file status with the following tags (followed by
        a space) at the start of each line:
 -t::
        Identify the file status with the following tags (followed by
        a space) at the start of each line:

-       H       cached
-       M       unmerged
-       R       removed/deleted
-       K       to be killed
-       ?       other
+       H::     cached
+       M::     unmerged
+       R::     removed/deleted
+       C::     modified/changed
+       K::     to be killed
+       ?::     other
+
+--full-name::
+       When run from a subdirectory, the command usually
+       outputs paths relative to the current directory.  This
+       option forces paths to be output relative to the project
+       top directory.
+
+--::
+       Do not interpret any more arguments as options.
+
+<file>::
+       Files to show. If no files are given all files which match the other
+       specified criteria are shown.

 
 Output
 ------
 
 Output
 ------


@@ -87,8 +108,12 @@ detailed information on unmerged paths.
 For an unmerged path, instead of recording a single mode/SHA1 pair,
 the dircache records up to three such pairs; one from tree O in stage
 1, A in stage 2, and B in stage 3.  This information can be used by
 For an unmerged path, instead of recording a single mode/SHA1 pair,
 the dircache records up to three such pairs; one from tree O in stage
 1, A in stage 2, and B in stage 3.  This information can be used by

-the user (or Cogito) to see what should eventually be recorded at the
-path. (see read-cache for more information on state)
+the user (or the porcelain) to see what should eventually be recorded at the
+path. (see git-read-tree for more information on state)
+
+When `-z` option is not used, TAB, LF, and backslash characters
+in pathnames are represented as `\t`, `\n`, and `\\`,
+respectively.

 
 
 Exclude Patterns
 
 
 Exclude Patterns


@@ -100,13 +125,13 @@ flags --others or --ignored are specified.
 
 These exclude patterns come from these places:
 
 
 These exclude patterns come from these places:
 

- (1) command line flag --exclude=<pattern> specifies a single
+  1. command line flag --exclude=<pattern> specifies a single

      pattern.
 
      pattern.
 

- (2) command line flag --exclude-from=<file> specifies a list of
+  2. command line flag --exclude-from=<file> specifies a list of

      patterns stored in a file.
 
      patterns stored in a file.
 

- (3) command line flag --exclude-per-directory=<name> specifies
+  3. command line flag --exclude-per-directory=<name> specifies

      a name of the file in each directory 'git-ls-files'
      examines, and if exists, its contents are used as an
      additional list of patterns.
      a name of the file in each directory 'git-ls-files'
      examines, and if exists, its contents are used as an
      additional list of patterns.


@@ -115,14 +140,14 @@ An exclude pattern file used by (2) and (3) contains one pattern
 per line.  A line that starts with a '#' can be used as comment
 for readability.
 
 per line.  A line that starts with a '#' can be used as comment
 for readability.
 

-The list of patterns that is in effect at a given time is
-built and ordered in the following way:
+There are three lists of patterns that are in effect at a given
+time.  They are built and ordered in the following way:

 
 

- * --exclude=<pattern> and lines read from --exclude-from=<file>
-   come at the beginning of the list of patterns, in the order
-   given on the command line.  Patterns that come from the file
-   specified with --exclude-from are ordered in the same order
-   as they appear in the file.
+ * --exclude=<pattern> from the command line; patterns are
+   ordered in the same order as they appear on the command line.
+
+ * lines read from --exclude-from=<file>; patterns are ordered
+   in the same order as they appear in the file.

 
  * When --exclude-per-directory=<name> is specified, upon
    entering a directory that has such a file, its contents are
 
  * When --exclude-per-directory=<name> is specified, upon
    entering a directory that has such a file, its contents are


@@ -130,11 +155,12 @@ built and ordered in the following way:
    are popped off when leaving the directory.
 
 Each pattern in the pattern list specifies "a match pattern" and
    are popped off when leaving the directory.
 
 Each pattern in the pattern list specifies "a match pattern" and

-optionally the fate --- either a file that matches the pattern
-is considered excluded or included.  By default, this being
-"exclude" mechanism, the fate is "excluded".  A filename is
-examined against the patterns in the list, and the first match
-determines its fate.
+optionally the fate; either a file that matches the pattern is
+considered excluded or included.  A filename is matched against
+the patterns in the three lists; the --exclude-from list is
+checked first, then the --exclude-per-directory list, and then
+finally the --exclude list. The last match determines its fate.
+If there is no match in the three lists, the fate is "included".

 
 A pattern specified on the command line with --exclude or read
 from the file specified with --exclude-from is relative to the
 
 A pattern specified on the command line with --exclude or read
 from the file specified with --exclude-from is relative to the


@@ -157,29 +183,31 @@ An exclude pattern is of the following format:
  - otherwise, it is a shell glob pattern, suitable for
    consumption by fnmatch(3) with FNM_PATHNAME flag.  I.e. a
    slash in the pattern must match a slash in the pathname.
  - otherwise, it is a shell glob pattern, suitable for
    consumption by fnmatch(3) with FNM_PATHNAME flag.  I.e. a
    slash in the pattern must match a slash in the pathname.

-   "Documentation/*.html" matches "Documentation/git.html" but
+   "Documentation/\*.html" matches "Documentation/git.html" but

    not "ppc/ppc.html".  As a natural exception, "/*.c" matches
    "cat-file.c" but not "mozilla-sha1/sha1.c".
 
 An example:
 
    not "ppc/ppc.html".  As a natural exception, "/*.c" matches
    "cat-file.c" but not "mozilla-sha1/sha1.c".
 
 An example:
 

+--------------------------------------------------------------

     $ cat .git/ignore
     # ignore objects and archives, anywhere in the tree.
     *.[oa]
     $ cat Documentation/.gitignore
     # ignore generated html files,
     $ cat .git/ignore
     # ignore objects and archives, anywhere in the tree.
     *.[oa]
     $ cat Documentation/.gitignore
     # ignore generated html files,

+    *.html

     # except foo.html which is maintained by hand
     !foo.html
     # except foo.html which is maintained by hand
     !foo.html

-    *.html

     $ git-ls-files --ignored \
         --exclude='Documentation/*.[0-9]' \
         --exclude-from=.git/ignore \
         --exclude-per-directory=.gitignore
     $ git-ls-files --ignored \
         --exclude='Documentation/*.[0-9]' \
         --exclude-from=.git/ignore \
         --exclude-per-directory=.gitignore

+--------------------------------------------------------------

 
 
 See Also
 --------
 
 
 See Also
 --------

-link:read-cache.html[read-cache]
+gitlink:git-read-tree[1]

 
 
 Author
 
 
 Author


@@ -192,5 +220,5 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel
 
 GIT
 ---
 
 GIT
 ---

-Part of the link:git.html[git] suite
+Part of the gitlink:git[7] suite