github.com/purpleclay/gitz@v0.8.2-0.20240515052600-43f80eea2fe1/docs/git/commit.md (about)

     1  ---
     2  icon: material/archive-lock-outline
     3  title: Committing changes to a repository
     4  description: Create a commit within the current repository and describe those changes with a given log message
     5  ---
     6  
     7  # Committing changes to a repository
     8  
     9  [:simple-git:{ .git-icon } Git Documentation](https://git-scm.com/docs/git-commit)
    10  
    11  Create a commit (_snapshot of changes_) within the current repository and describe those changes with a given log message. A commit will only exist within the local history until pushed back to the repository remote.
    12  
    13  ## Commit a Snapshot of Repository Changes
    14  
    15  Calling `Commit` with a message will create a new commit within the repository:
    16  
    17  ```{ .go .select linenums="1" }
    18  package main
    19  
    20  import (
    21      "log"
    22  
    23      git "github.com/purpleclay/gitz"
    24  )
    25  
    26  func main() {
    27      client, _ := git.NewClient()
    28  
    29      // stage all changes to files and folders
    30  
    31      _, err := client.Commit("feat: a brand new feature")
    32      if err != nil {
    33          log.Fatal("failed to commit latest changes within repository")
    34      }
    35  }
    36  ```
    37  
    38  And to verify its creation:
    39  
    40  ```{ .text .no-select .no-copy }
    41  $ git log -n1
    42  
    43  commit 703a6c9bc9ee91d0c226b169b131670fb92d9a0a (HEAD -> main)
    44  Author: Purple Clay <**********(at)*******>
    45  Date:   Mon Feb 20 20:43:49 2023 +0000
    46  
    47      feat: a brand new feature
    48  ```
    49  
    50  ## Allowing an empty commit
    51  
    52  You can create empty commits without staging any files using the `WithAllowEmpty` option.
    53  
    54  ```{ .go .select linenums="1" }
    55  package main
    56  
    57  import (
    58      "log"
    59  
    60      git "github.com/purpleclay/gitz"
    61  )
    62  
    63  func main() {
    64      client, _ := git.NewClient()
    65      client.Commit("no files are staged here", git.WithAllowEmpty())
    66  }
    67  ```
    68  
    69  ## Signing a commit using GPG
    70  
    71  Any commit to a repository can be GPG signed by an author to prove its authenticity through GPG verification. By setting the `commit.gpgSign` and `user.signingKey` git config options, GPG signing, can become an automatic process. `gitz` provides options to control this process and manually overwrite existing settings per commit.
    72  
    73  ### Sign an individual commit
    74  
    75  If the `commit.gpgSign` git config setting is not enabled; you can selectively GPG sign a commit using the `WithGpgSign` option.
    76  
    77  ```{ .go .select linenums="1" }
    78  package main
    79  
    80  import (
    81      "log"
    82  
    83      git "github.com/purpleclay/gitz"
    84  )
    85  
    86  func main() {
    87      client, _ := git.NewClient()
    88  
    89      _, err := client.Commit("no files are staged here",
    90          git.WithAllowEmpty(),
    91          git.WithGpgSign())
    92      if err != nil {
    93          log.Fatal("failed to gpg sign commit with user.signingKey")
    94      }
    95  }
    96  ```
    97  
    98  ### Select a GPG signing key
    99  
   100  If multiple GPG keys exist, you can cherry-pick a key during a commit using the `WithGpgSigningKey` option, overriding the `user.signingKey` git config setting, if set.
   101  
   102  ```{ .go .select linenums="1" }
   103  package main
   104  
   105  import (
   106      "log"
   107  
   108      git "github.com/purpleclay/gitz"
   109  )
   110  
   111  func main() {
   112      client, _ := git.NewClient()
   113  
   114      _, err := client.Commit("no files are staged here",
   115          git.WithAllowEmpty(),
   116          git.WithGpgSigningKey("E5389A1079D5A52F"))
   117      if err != nil {
   118          log.Fatal("failed to gpg sign commit with provided public key")
   119      }
   120  }
   121  ```
   122  
   123  ### Prevent a commit from being signed
   124  
   125  You can disable the GPG signing of a commit by using the `WithNoGpgSign` option, overriding the `commit.gpgSign` git config setting, if set.
   126  
   127  ```{ .go .select linenums="1" }
   128  package main
   129  
   130  import (
   131      "log"
   132  
   133      git "github.com/purpleclay/gitz"
   134  )
   135  
   136  func main() {
   137      client, _ := git.NewClient()
   138      client.Commit("prevent commit from being signed",
   139          git.WithAllowEmpty(),
   140          git.WithNoGpgSign())
   141  }
   142  ```
   143  
   144  ## Providing git config at execution
   145  
   146  You can provide git config through the `WithCommitConfig` option to only take effect during the execution of a `Commit`, removing the need to change config permanently.