gitignore

README

gitignore

Package gitignore provides a simple way to parse .gitignore files and match paths against the rules defined in those files. The package tries to implement the gitignore specification as defined in the git documentation, but it is not guaranteed to be 100% accurate.

gitignore is kind of a fork of sabhiram/go-gitignore, as a lot of the logic comes from that package, but offers a different public API, usage of modern Go features, and is actively maintained.

As the package uses the standard regexp package for the bulk of its logic, performance for big files could be improved. Patches are welcome!

Installation

To install gitignore and use it in your project, run:

go get git.sr.ht/~jamesponddotco/gitignore-go@latest

Usage

To parse a .gitignore file and use it to match a path, call gitignore.New with the path to the .gitignore file as an argument, and then call .Match with the path to be matched as an argument.

package main

import (
	"log"

	"git.sr.ht/~jamesponddotco/gitignore-go"
)

func main() {
	matcher, err := gitignore.New("/path/to/.gitignore")
	if err != nil {
		log.Fatal(err)
	}

	// Match the given path against the rules defined in the .gitignore file and
	// do something with it.
	if matcher.Match("/path/to/file.txt") {
		log.Println("File is ignored.")
	} else {
		log.Println("File is not ignored.")
	}
}

You can also use gitignore.NewFromLines to parse a slice of strings representing the lines of a .gitignore file, if you prefer.

Contributing

Anyone can help make gitignore better. Send patches on the mailing list and report bugs on the issue tracker.

You must sign-off your work using git commit --signoff. Follow the Linux kernel developer's certificate of origin for more details.

All contributions are made under the MIT License.

Resources

The following resources are available:

• Package documentation.
• Support and general discussions.
• Patches and development related questions.
• Instructions on how to prepare patches.
• Feature requests and bug reports.

---

Released under the MIT License.

Documentation

Overview

Package gitignore provides functionality to parse .gitignore files and match paths against the rules defined in those files.

The package tries to implement the gitignore specification as defined in the git documentation. It supports all standard gitignore features including pattern negation, directory-specific patterns, and wildcards.

Basic usage:

matcher, err := gitignore.New("/givePath/to/.gitignore")
if err != nil {
	// Handle error
}

if matcher.Match("givePath/to/file.txt") {
	// Path is ignored
}

The package provides two ways to create a matcher:

1. From a file using New().
2. From a slice of pattern strings using NewFromLines().

Index

• Constants
• type File
  • func New(path string) (*File, error)
  • func NewFromLines(lines []string) (*File, error)
  • func (f *File) Match(path string) bool

Constants

const ErrRegexCompile xerrors.Error = "failed to compile regex"

ErrRegexCompile is returned when an error occurs while compiling regular expressions when parsing a .gitignore file.

Types

type File

type File struct {
	// contains filtered or unexported fields
}

File represents a .gitignore file and provides the functionality to match paths against its rules.

func New

func New(path string) (*File, error)

New creates a new File instance from a given .gitignore file.

func NewFromLines

func NewFromLines(lines []string) (*File, error)

NewFromLines creates a new File instance from a list of strings. Useful when patterns are available in memory rather than in a file or for testing.

func (*File) Match

func (f *File) Match(path string) bool

Match checks if the given path matches any of the .gitignore rules, and return true if the path should be ignored according to the rules.

The path is normalized to use forward slashes (/) regardless of the operating system.