FD(1)                       General Commands Manual                      FD(1)



NNAAMMEE
       fd - find entries in the filesystem

SSYYNNOOPPSSIISS
       ffdd  [--HHIIEEssiiaaLLpp00hhVV]  [--dd  _d_e_p_t_h] [--tt _f_i_l_e_t_y_p_e] [--ee _e_x_t] [--EE _e_x_c_l_u_d_e] [--cc
       _w_h_e_n] [--jj _n_u_m] [--xx _c_m_d] [_p_a_t_t_e_r_n] [_p_a_t_h_._._.]

DDEESSCCRRIIPPTTIIOONN
       ffdd is a simple, fast and user-friendly alternative to ffiinndd(1).

       By default ffdd uses regular expressions for the pattern.  However,  this
       can be changed to use simple glob patterns with the '--glob' option.

OOPPTTIIOONNSS
       --HH,, ----hhiiddddeenn
              Include  hidden  files  and  directories  in  the search results
              (default: hidden files and directories are  skipped).  The  flag
              can be overridden with '--no-hidden'.

       --II,, ----nnoo--iiggnnoorree
              Show search results from files and directories that would other‐
              wise be ignored by

              · _._g_i_t_i_g_n_o_r_e

              · _._g_i_t_/_i_n_f_o_/_e_x_c_l_u_d_e

              · The global gitignore  configuration  (by  default  _$_H_O_M_E_/_._c_o_n_‐
                _f_i_g_/_g_i_t_/_i_g_n_o_r_e)

              · _._i_g_n_o_r_e

              · _._f_d_i_g_n_o_r_e

              · The global fd ignore file (usually _$_H_O_M_E_/_._c_o_n_f_i_g_/_f_d_/_i_g_n_o_r_e )

              The flag can be overridden with '--ignore'.

       --uu,, ----uunnrreessttrriicctteedd
              Alias  for '--no-ignore'. Can be repeated; '-uu' is an alias for
              '--no-ignore --hidden'.

       ----nnoo--iiggnnoorree--vvccss
              Show search results from files and directories that would other‐
              wise   be  ignored  by  gitignore  files  including  _._g_i_t_i_g_n_o_r_e,
              _._g_i_t_/_i_n_f_o_/_e_x_c_l_u_d_e,  and  the  global   gitignore   configuration
              (_c_o_r_e_._e_x_c_l_u_d_e_s_F_i_l_e  git  setting,  which defaults to _$_H_O_M_E_/_._c_o_n_‐
              _f_i_g_/_g_i_t_/_i_g_n_o_r_e).  The flag can  be  overridden  with  '--ignore-
              vcs'.

       ----nnoo--iiggnnoorree--ppaarreenntt
              Show search results from files and directories that would other‐
              wise be ignored by gitignore files in parent directories.

       --ss,, ----ccaassee--sseennssiittiivvee
              Perform a case-sensitive search. By default, fd uses case-insen‐
              sitive  searches, unless the pattern contains an uppercase char‐
              acter (smart case).

       --ii,, ----iiggnnoorree--ccaassee
              Perform a case-insensitive search. By  default,  fd  uses  case-
              insensitive  searches,  unless the pattern contains an uppercase
              character (smart case).

       --gg,, ----gglloobb
              Perform a glob-based search  instead  of  a  regular  expression
              search.   If combined with the '--full-path' option, '**' can be
              used to match multiple path components.

       ----rreeggeexx
              Perform a regular-expression based search (default). This can be
              used to override --glob.

       --FF,, ----ffiixxeedd--ssttrriinnggss
              Treat  the  pattern  as  a  literal  string instead of a regular
              expression. Note that this also performs  substring  comparison.
              If  you  want  to  match  on  an  exact filename, consider using
              '--glob'.

       --aa,, ----aabbssoolluuttee--ppaatthh
              Shows the full path starting from the root as opposed  to  rela‐
              tive paths.  The flag can be overridden with '--relative-path'.

       --ll,, ----lliisstt--ddeettaaiillss
              Use a detailed listing format like 'ls -l'. This is basically an
              alias  for  '--exec-batch  ls  -l'  with  some  additional  'ls'
              options.  This can be used to see more metadata, to show symlink
              targets and to achieve a deterministic sort order.

       --LL,, ----ffoollllooww
              By default, fd does  not  descend  into  symlinked  directories.
              Using this flag, symbolic links are also traversed. The flag can
              be overridden with '--no-follow'.

       --pp,, ----ffuullll--ppaatthh
              By default, the search pattern is only matched against the file‐
              name  (or  directory  name).  Using  this  flag,  the _p_a_t_t_e_r_n is
              matched against the full path.

       --00,, ----pprriinntt00
              Separate search results by the null character (instead  of  new‐
              lines). Useful for piping results to _x_a_r_g_s.

       ----mmaaxx--rreessuullttss ccoouunntt
              Limit  the  number of search results to 'count' and quit immedi‐
              ately.

       --11     Limit the search to a single result and quit  immediately.  This
              is an alias for '--max-results=1'.

       --qq,, ----qquuiieett
              When  the  flag  is present, the program does not print anything
              and will instead exit with a code of 0 if there is at least  one
              search  result.   Otherwise,  the  exit code will be 1.  This is
              mainly for usage in scripts and can be faster than checking  for
              output  because  the search can be stopped early after the first
              match.  ----hhaass--rreessuullttss can be used as an alias.

       ----sshhooww--eerrrroorrss
              Enable the display of filesystem errors for situations  such  as
              insufficient permissions or dead symlinks.

       ----ssttrriipp--ccwwdd--pprreeffiixx
              By  default, relative paths are prefixed with './' when the out‐
              put goes to a non interactive terminal (TTY). Use this  flag  to
              disable this behaviour.

       ----oonnee--ffiillee--ssyysstteemm,, ----mmoouunntt,, ----xxddeevv
              By  default,  fd  will  traverse  the file system tree as far as
              other options dictate. With this flag, fd ensures that  it  does
              not descend into a different file system than the one it started
              in. Comparable to the -mount or -xdev filters of find(1).

       --hh,, ----hheellpp
              Print help information.

       --VV,, ----vveerrssiioonn
              Print version information.

       --dd,, ----mmaaxx--ddeepptthh _d
              Limit directory traversal to at  most  _d  levels  of  depth.  By
              default, there is no limit on the search depth.

       ----mmiinn--ddeepptthh _d
              Only  show search results starting at the given depth. See also:
              '--max-depth' and '--exact-depth'.

       ----eexxaacctt--ddeepptthh _d
              Only show search results at the exact given depth.  This  is  an
              alias for '--min-depth <depth> --max-depth <depth>'.

       ----pprruunnee
              Do not traverse into matching directories.

       --tt,, ----ttyyppee _f_i_l_e_t_y_p_e
              Filter search by type:

              f, file
                     regular files

              d, directory
                     directories

              l, symlink
                     symbolic links

              s, socket
                     sockets

              p, pipe
                     named pipes (FIFOs)

              x, executable
                     executable (files)

              e, empty
                     empty files or directories

              This  option can be specified more than once to include multiple
              file types.  Searching for '--type  file  --type  symlink'  will
              show both regular files as well as symlinks. Note that the 'exe‐
              cutable' and 'empty'  filters  work  differently:  '--type  exe‐
              cutable'  implies  '--type  file' by default. And '--type empty'
              searches for empty files and directories, unless either  '--type
              file' or '--type directory' is specified in addition.

              Examples:
                - Only search for files:
                    fd --type file â¦
                    fd -tf â¦
                - Find both files and symlinks
                    fd --type file --type symlink â¦
                    fd -tf -tl â¦
                - Find executable files:
                    fd --type executable
                    fd -tx
                - Find empty files:
                    fd --type empty --type file
                    fd -te -tf
                - Find empty directories:
                    fd --type empty --type directory
                    fd -te -td

       --ee,, ----eexxtteennssiioonn _e_x_t
              Filter search results by file extension _e_x_t.  This option can be
              used repeatedly to allow for multiple possible file extensions.

              If you want to search for files without extension, you  can  use
              the regex '^[^.]+$' as a normal search pattern.

       --EE,, ----eexxcclluuddee _p_a_t_t_e_r_n
              Exclude  files/directories  that  match  the given glob pattern.
              This overrides any other ignore logic.   Multiple  exclude  pat‐
              terns can be specified.  Examples:
                --exclude '*.pyc'
                --exclude node_modules

       ----iiggnnoorree--ffiillee _p_a_t_h
              Add  a  custom  ignore-file in '.gitignore' format.  These files
              have a low precedence.

       --cc,, ----ccoolloorr _w_h_e_n
              Declare _w_h_e_n to colorize search results:

              auto   Colorize output when standard output is connected to ter‐
                     minal (default).

              never  Do not colorize output.

              always Always colorize output.

       --jj,, ----tthhrreeaaddss _n_u_m
              Set number of threads to use for searching & executing (default:
              number of available CPU cores).

       --SS,, ----ssiizzee _s_i_z_e
              Limit results based on  the  size  of  files  using  the  format
              _<_+_-_>_<_N_U_M_>_<_U_N_I_T_>

              '+'    file size must be greater than or equal to this

              '-'    file size must be less than or equal to this

              If  neither  '+' nor '-' is specified, file size must be exactly
              equal to this.

              'NUM'  The numeric size (e.g. 500)

              'UNIT' The units for NUM. They are not case-sensitive.   Allowed
                     unit values:

                     'b'    bytes

                     'k'    kilobytes (base ten, 10^3 = 1000 bytes)

                     'm'    megabytes

                     'g'    gigabytes

                     't'    terabytes

                     'ki'   kibibytes (base two, 2^10 = 1024 bytes)

                     'mi'   mebibytes

                     'gi'   gibibytes

                     'ti'   tebibytes

       ----cchhaannggeedd--wwiitthhiinn _d_a_t_e_|_d_u_r_a_t_i_o_n
              Filter  results based on the file modification time.  Files with
              modification times greater than the argument will  be  returned.
              The  argument  can be provided as a duration (_1_0_h_, _1_d_, _3_5_m_i_n) or
              as a specific point in time in either full RFC3339  format  with
              time  zone,  or  as  a  date  or datetime in the local time zone
              (_Y_Y_Y_Y_-_M_M_-_D_D or _Y_Y_Y_Y_-_M_M_-_D_D _H_H_:_M_M_:_S_S).  ----cchhaannggee--nneewweerr--tthhaann can be
              used as an alias.

              Examples:
                --changed-within 2weeks
                --change-newer-than "2018-10-27 10:00:00"

       ----cchhaannggeedd--bbeeffoorree _d_a_t_e_|_d_u_r_a_t_i_o_n
              Filter  results based on the file modification time.  Files with
              modification times less than the argument will be returned.  The
              argument  can be provided as a duration (_1_0_h_, _1_d_, _3_5_m_i_n) or as a
              specific point in time in either full RFC3339 format  with  time
              zone,  or as a date or datetime in the local time zone (_Y_Y_Y_Y_-_M_M_-
              _D_D or _Y_Y_Y_Y_-_M_M_-_D_D _H_H_:_M_M_:_S_S).  ----cchhaannggee--oollddeerr--tthhaann can be used  as
              an alias.

              Examples:
                --changed-before "2018-10-27 10:00:00"
                --change-older-than 2weeks

       --oo,, ----oowwnneerr _[_u_s_e_r_]_[_:_g_r_o_u_p_]
              Filter    files    by   their   user   and/or   group.   Format:
              [(user|uid)][:(group|gid)]. Either  side  is  optional.  Precede
              either side with a '!' to exclude files instead.

              Examples:
                --owner john
                --owner :students
                --owner "!john:students"

       ----bbaassee--ddiirreeccttoorryy _p_a_t_h
              Change the current working directory of fd to the provided path.
              This means that search results will be shown with respect to the
              given base path. Note that relative paths which are passed to fd
              via the positional _p_a_t_h argument  or  the  ----sseeaarrcchh--ppaatthh  option
              will also be resolved relative to this directory.

       ----ppaatthh--sseeppaarraattoorr _s_e_p_a_r_a_t_o_r
              Set  the  path  separator  to  use when printing file paths. The
              default is the OS-specific separator ('/' on Unix, '\'  on  Win‐
              dows).

       ----sseeaarrcchh--ppaatthh _s_e_a_r_c_h_-_p_a_t_h
              Provide paths to search as an alternative to the positional _p_a_t_h
              argument. Changes the usage to ´fd [FLAGS/OPTIONS] --search-path
              PATH --search-path PATH2 [PATTERN]´

       --xx,, ----eexxeecc _c_o_m_m_a_n_d
              Execute   _c_o_m_m_a_n_d  for  each  search  result  in  parallel  (use
              --threads=1 for sequential command execution).

              Note that all subsequent positional arguments are considered  to
              be arguments to the _c_o_m_m_a_n_d - not to fd.  It is therefore recom‐
              mended to place the -x/--exec option  last.  Alternatively,  you
              can  supply a ';' argument to end the argument list and continue
              with more fd options.  Most shells require ';'  to  be  escaped:
              '\;'.   This  option  can  be specified multiple times, in which
              case all commands are run for each file found, in the order they
              are  provided.  In that case, you must supply a ';' argument for
              all but the last commands.

              The following placeholders are substituted before the command is
              executed:

                     {}     path (of the current search result)

                     {/}    basename

                     {//}   parent directory

                     {.}    path without file extension

                     {/.}   basename without file extension

              If  no  placeholder  is  present, an implicit "{}" at the end is
              assumed.

              Examples:

                - find all *.zip files and unzip them:

                      fd -e zip -x unzip

                - find *.h and *.cpp files and run "clang-format  -i  .."  for
              each of them:

                      fd -e h -e cpp -x clang-format -i

                - Convert all *.jpg files to *.png files:

                      fd -e jpg -x convert {} {.}.png

       --XX,, ----eexxeecc--bbaattcchh _c_o_m_m_a_n_d
              Execute _c_o_m_m_a_n_d once, with all search results as arguments.  One
              of the following placeholders is substituted before the  command
              is executed:

                     {}     path (of all search results)

                     {/}    basename

                     {//}   parent directory

                     {.}    path without file extension

                     {/.}   basename without file extension

              If  no  placeholder  is  present, an implicit "{}" at the end is
              assumed.

              Like --exec, this can be used multiple times, in which case each
              command will be run in the order given.

              Examples:

                - Find all test_*.py files and open them in your favorite edi‐
              tor:

                      fd -g 'test_*.py' -X vim

                  Note that this executes a  single  "vim"  process  with  all
              search results as arguments.

                - Find all *.rs files and count the lines with "wc -l ...":

                      fd -e rs -X wc -l

       ----bbaattcchh--ssiizzee _s_i_z_e
              Maximum  number  of  arguments to pass to the command given with
              -X. If the number of results is greater than the given size, the
              command  given  with -X is run again with remaining arguments. A
              batch size of zero means there is no limit.

PPAATTTTEERRNN SSYYNNTTAAXX
       The regular expression syntax used by fd is documented here:

           https://docs.rs/regex/1.0.0/regex/#syntax

       The glob syntax is documented here:

           https://docs.rs/globset/#syntax

EENNVVIIRROONNMMEENNTT
       LLSS__CCOOLLOORRSS
              Determines how to colorize search results, see ddiirrccoolloorrss(1)..

       NNOO__CCOOLLOORR
              Disables colorized output.

       XXDDGG__CCOONNFFIIGG__HHOOMMEE,, HHOOMMEE
              Used to locate the global ignore  file.  If  XXDDGG__CCOONNFFIIGG__HHOOMMEE  is
              set, use _$_X_D_G___C_O_N_F_I_G___H_O_M_E_/_f_d_/_i_g_n_o_r_e.  Otherwise, use _$_H_O_M_E_/_._c_o_n_‐
              _f_i_g_/_f_d_/_i_g_n_o_r_e.

EEXXAAMMPPLLEESS
       Find files and directories that match the pattern '_n_e_e_d_l_e':
              $ fd needle

       Start a search in a given directory (_/_v_a_r_/_l_o_g):
              $ fd nginx /var/log

       Find all Python files (all files with the extension _._p_y) in the current
       directory:
              $ fd -e py

       Open all search results with vim:
              $ fd pattern -X vim

       ----bbaattcchh--ssiizzee _s_i_z_e
              Pass  at  most  _s_i_z_e arguments to each call to the command given
              with -X.


       SSEEEE AALLSSOO
              ffiinndd(1)



                                                                         FD(1)
