github.com/nemith/go-gitlog@v0.0.2-0.20180205151741-6c79beb2287b/README.md (about)

     1  # go-gitlog
     2  
     3  [![godoc.org](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square)](https://godoc.org/github.com/tsuyoshiwada/go-gitlog)
     4  [![Travis](https://img.shields.io/travis/tsuyoshiwada/go-gitlog.svg?style=flat-square)](https://travis-ci.org/tsuyoshiwada/go-gitlog)
     5  [![MIT License](http://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://github.com/tsuyoshiwada/go-gitlog/blob/master/LICENSE)
     6  
     7  > Go (golang) package for providing a means to handle git-log.
     8  
     9  
    10  
    11  
    12  ## Installation
    13  
    14  To install `go-gitlog`, simply run:
    15  
    16  ```bash
    17  $ go get -u github.com/tsuyoshiwada/go-gitlog
    18  ```
    19  
    20  
    21  
    22  
    23  ## Usage
    24  
    25  It is the simplest example.
    26  
    27  ```go
    28  package main
    29  
    30  import (
    31  	"log"
    32  	"github.com/tsuyoshiwada/go-gitlog"
    33  )
    34  
    35  func main() {
    36  	// New gitlog
    37  	git := gitlog.New(&gitlog.Config{
    38  		Bin:  "/your/custom/git/bin", // default "git"
    39  		Path: "/repo/path/to",        // default "."
    40  	})
    41  
    42  	// List git-log
    43  	commits, err := git.Log(nil, nil)
    44  	if err != nil {
    45  		log.Fatalln(err)
    46  	}
    47  
    48  	// Output
    49  	for _, commit := range commits {
    50  		fmt.Printf(
    51  			"%s %s %s\n",
    52  			commit.Hash.Short,
    53  			commit.Author.Name,
    54  			commit.Subject,
    55  		)
    56  	}
    57  }
    58  ```
    59  
    60  See [godoc](https://godoc.org/github.com/tsuyoshiwada/go-gitlog) for API detail of [Log](https://godoc.org/github.com/tsuyoshiwada/go-gitlog#GitLog) :+1:
    61  
    62  
    63  
    64  
    65  ## Options
    66  
    67  By using [Params](https://godoc.org/github.com/tsuyoshiwada/go-gitlog#Params) you can customize the log retrieval.
    68  
    69  
    70  ### `MergesOnly`
    71  
    72  Give the `--merges` option.
    73  
    74  
    75  ### `IgnoreMerges`
    76  
    77  Give the `--no-merges` option.
    78  
    79  
    80  ### `Reverse`
    81  
    82  Give the `--reverse` option.
    83  
    84  
    85  
    86  
    87  ## Examples
    88  
    89  
    90  ### `$ git log <sha1|tag|ref>`
    91  
    92  Specification of `revisionrange` can be realized by giving a [RevArgs](https://godoc.org/github.com/tsuyoshiwada/go-gitlog#RevArgs) interface.
    93  
    94  ```go
    95  commits, err := git.Log(&gitlog.Rev{"5e312d5"}, nil)
    96  ```
    97  
    98  
    99  ### `$ git log <sha1|tag|ref>..<sha1|tag|ref>`
   100  
   101  For double dot notation use [RevRange](https://godoc.org/github.com/tsuyoshiwada/go-gitlog#RevRange).
   102  
   103  ```go
   104  commits, err := git.Log(&gitlog.RevRange{
   105  	Old: "v0.1.7",
   106  	New: "v1.2.3",
   107  }, nil)
   108  ```
   109  
   110  
   111  ### `$ git log -n <n>`
   112  
   113  Use [RevNumber](https://godoc.org/github.com/tsuyoshiwada/go-gitlog#RevNumber) to get the specified number of commits.
   114  
   115  ```go
   116  commits, err := git.Log(&gitlog.RevNumber{10}, nil)
   117  ```
   118  
   119  
   120  ### `$ git log --since <time> --until <time>`
   121  
   122  By using [RevTime](https://godoc.org/github.com/tsuyoshiwada/go-gitlog#RevTime) you can specify the range by time.
   123  
   124  **Since and Until:**
   125  
   126  ```go
   127  commits, err := git.Log(&gitlog.RevTime{
   128  	Since: time.Date(2018, 3, 4, 23, 0, 0, time.UTC),
   129  	Until: time.Date(2018, 1, 2, 12, 0, 0, time.UTC),
   130  }, nil)
   131  ```
   132  
   133  **Only since:**
   134  
   135  ```go
   136  commits, err := git.Log(&gitlog.RevTime{
   137  	Since: time.Date(2018, 1, 2, 12, 0, 0, time.UTC),
   138  }, nil)
   139  ```
   140  
   141  **Only until:**
   142  
   143  ```go
   144  commits, err := git.Log(&gitlog.RevTime{
   145  	Until: time.Date(2018, 1, 2, 12, 0, 0, time.UTC),
   146  }, nil)
   147  ```
   148  
   149  
   150  
   151  
   152  ## How it works
   153  
   154  Internally we use the git command to format it with the `--pretty` option of log and parse the standard output.  
   155  So, only local git repositories are eligible for acquisition.
   156  
   157  
   158  
   159  
   160  ## Contribute
   161  
   162  1. Fork (https://github.com/tsuyoshiwada/go-gitlog)
   163  1. Create a feature branch
   164  1. Commit your changes
   165  1. Rebase your local changes against the master branch
   166  1. Run test suite with the `go test` command and confirm that it passes
   167  1. Create new Pull Request :muscle:
   168  
   169  Bugs, feature requests and comments are more than welcome in the [issues](https://github.com/tsuyoshiwada/go-gitlog/issues).
   170  
   171  
   172  
   173  
   174  ## License
   175  
   176  [MIT © tsuyoshiwada](./LICENSE)