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.