github.com/boyter/gocodewalker@v1.3.2/README.md (about)

     1  # gocodewalker
     2  
     3  [![Go Report Card](https://goreportcard.com/badge/github.com/boyter/gocodewalker)](https://goreportcard.com/report/github.com/boyter/gocodewalker)
     4  [![Str Count Badge](https://sloc.xyz/github/boyter/gocodewalker/)](https://github.com/boyter/gocodewalker/)
     5  
     6  Library to help with walking of code directories in Go. 
     7  
     8  The problem. You want to walk the directories of a code repository. You want to respect .gitignore and .ignore files, and 
     9  some are nested. This library is the answer.
    10  
    11   - Designed to walk code repositories or find the root of them.
    12   - By default, respects both .gitignore and .ignore files (can be disabled) and nested ones for accuracy
    13   - Has configurable options for skipping files based on regex, extension or general match
    14   - Uses readdir to provide as fast as possible file walking
    15  
    16  NB this was moved from go-code-walker due to the name being annoying and to ensure it has a unique package name. Should still be drop in replaceable
    17  so long as you refer to the new package name.
    18  
    19  https://pkg.go.dev/github.com/boyter/gocodewalker
    20  
    21  Package provides file operations specific to code repositories such as walking the file tree obeying .ignore and .gitignore files
    22  or looking for the root directory assuming already in a git project.
    23  
    24  Example of usage,
    25  
    26  ```go
    27  fileListQueue := make(chan *gocodewalker.File, 100)
    28  
    29  fileWalker := gocodewalker.NewFileWalker(".", fileListQueue)
    30  
    31  // restrict to only process files that have the .go extension
    32  fileWalker.AllowListExtensions = append(fileWalker.AllowListExtensions, "go")
    33  
    34  // handle the errors by printing them out and then ignore
    35  errorHandler := func(e error) bool {
    36      fmt.Println("ERR", e.Error())
    37      return true
    38  }
    39  fileWalker.SetErrorHandler(errorHandler)
    40  
    41  go fileWalker.Start()
    42  
    43  for f := range fileListQueue {
    44      fmt.Println(f.Location)
    45  }
    46  ```
    47  
    48  The above by default will recursively add files to the fileListQueue respecting both .ignore and .gitignore files if found, and
    49  only adding files with the go extension into the queue.
    50  
    51  You can also run the walker in parallel with the results intermixed if required,
    52  
    53  ```go
    54  fileListQueue := make(chan *gocodewalker.File, 100)
    55  
    56  fileWalker := gocodewalker.NewParallelFileWalker([]string{".", "someotherdir"}, fileListQueue)
    57  go fileWalker.Start()
    58  
    59  for f := range fileListQueue {
    60      fmt.Println(f.Location)
    61  }
    62  ```
    63  
    64  All code is dual-licenced as either MIT or Unlicence.
    65  
    66  ### Error Handler
    67  
    68  You can supply your own error handler when walking. This allows you to perform an action when there is an error
    69  and decide if the walker should continue to process, or return.
    70  
    71  The simplest handler is the below, which if set will swallow all errors and continue as best it can.
    72  
    73  ```go
    74  errorHandler := func(e error) bool {
    75      return true
    76  }
    77  fileWalker.SetErrorHandler(errorHandler)
    78  ```
    79  
    80  If you wanted to return on errors you could use the following.
    81  
    82  ```go
    83  errorHandler := func(e error) bool {
    84      return false
    85  }
    86  fileWalker.SetErrorHandler(errorHandler)
    87  ```
    88  
    89  If you wanted to terminate walking on an error you could use the following, which would cause it to return the error,
    90  and then terminate all walking. This might be desirable where any error indicates a total failure.
    91  
    92  ```go
    93  errorHandler := func(e error) bool {
    94      fileWalker.Terminate()
    95      return false
    96  }
    97  fileWalker.SetErrorHandler(errorHandler)
    98  ```
    99  
   100  ### Testing
   101  
   102  Done through unit/integration tests. Otherwise see https://github.com/svent/gitignore-test
   103  
   104  See `./cmd/gocodewalker/main.go` for an example of how to implement and validate 
   105  
   106  ### Info
   107  
   108  Details on how gitignores work
   109  
   110  https://stackoverflow.com/questions/71735516/proper-way-to-setup-multiple-gitignore-files-in-nested-folders-of-a-repository