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

     1  ---
     2  icon: material/arrow-right-bold-box-outline
     3  title: Pushing the latest changes back to a remote
     4  description: Push all local repository changes back to the remote
     5  ---
     6  
     7  # Pushing the latest changes back to a remote
     8  
     9  [:simple-git:{ .git-icon } Git Documentation](https://git-scm.com/docs/git-push)
    10  
    11  Push all local repository changes back to the remote, ensuring the remote now tracks all references.
    12  
    13  ## Pushing locally committed changes
    14  
    15  Calling `Push` without any options will attempt to push all locally committed changes back to the remote for the current branch:
    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      // all changes have been staged and committed locally
    30  
    31      _, err := client.Push()
    32      if err != nil {
    33          log.Fatal("failed to push committed changes to the remote")
    34      }
    35  }
    36  ```
    37  
    38  ## Pushing all local branches
    39  
    40  To push changes spread across multiple branches back to the remote in a single atomic operation, use the `WillAllBranches` option:
    41  
    42  ```{ .go .select linenums="1" }
    43  package main
    44  
    45  import (
    46      "log"
    47  
    48      git "github.com/purpleclay/gitz"
    49  )
    50  
    51  func main() {
    52      client, _ := git.NewClient()
    53  
    54      // modifications are made to multiple files across two
    55      // different branches
    56      //
    57      // b: new-feature
    58      //  > client.go
    59      // b: new-bug-fix
    60      //  > parser.go
    61  
    62      _, err := client.Push(git.WithAllBranches())
    63      if err != nil {
    64          log.Fatal("failed to stage files")
    65      }
    66  }
    67  ```
    68  
    69  ## Pushing all local tags
    70  
    71  All locally created tags can also be pushed back to the remote in a single atomic operation using the `WithAllTags` option:
    72  
    73  ```{ .go .select linenums="1" }
    74  package main
    75  
    76  import (
    77      "log"
    78  
    79      git "github.com/purpleclay/gitz"
    80  )
    81  
    82  func main() {
    83      client, _ := git.NewClient()
    84  
    85      // multiple tags are created locally, 1.0.0 and v1
    86  
    87      _, err := client.Push(git.WithAllTags())
    88      if err != nil {
    89          log.Fatal("failed to stage files")
    90      }
    91  }
    92  ```
    93  
    94  ## Cherry-pick what is pushed to the remote
    95  
    96  The `WithRefSpecs` option provides greater freedom to cherry-pick locally created references (_branches and tags_) and push them back to the remote. A reference can be as simple as a name or as explicit as providing a source (_local_) to destination (_remote_) mapping. Please read the official git specification on how to construct [refspecs](https://git-scm.com/docs/git-push#Documentation/git-push.txt-ltrefspecgt82308203).
    97  
    98  ```{ .go .select linenums="1" }
    99  package main
   100  
   101  import (
   102      "log"
   103  
   104      git "github.com/purpleclay/gitz"
   105  )
   106  
   107  func main() {
   108      client, _ := git.NewClient()
   109  
   110      // new branch and tag are created locally
   111  
   112      _, err := client.Push(git.WithRefSpecs("0.1.0", "new-branch"))
   113      if err != nil {
   114          log.Fatal("failed to stage files")
   115      }
   116  }
   117  ```
   118  
   119  ## Push options
   120  
   121  Support the transmission of arbitrary strings to the remote server using the `WithPushOptions` option.
   122  
   123  ```{ .go .select linenums="1" }
   124  package main
   125  
   126  import (
   127      "log"
   128  
   129      git "github.com/purpleclay/gitz"
   130  )
   131  
   132  func main() {
   133      client, _ := git.NewClient()
   134  
   135      // all changes have been staged and committed locally
   136  
   137      _, err := client.Push(git.WithPushOptions("ci.skip=true"))
   138      if err != nil {
   139          log.Fatal("failed to push committed changes to the remote")
   140      }
   141  }
   142  ```
   143  
   144  ## Deleting references from the remote
   145  
   146  Delete any number of references from the remote by using the `WithDeleteRefSpecs` option.
   147  
   148  ```{ .go .select linenums="1" }
   149  package main
   150  
   151  import (
   152      "log"
   153  
   154      git "github.com/purpleclay/gitz"
   155  )
   156  
   157  func main() {
   158      client, _ := git.NewClient()
   159  
   160      // a tag and branch have been deleted locally
   161  
   162      _, err := client.Push(git.WithDeleteRefSpecs("branch", "0.1.0"))
   163      if err != nil {
   164          log.Fatal("failed to delete references from the remote")
   165      }
   166  }
   167  ```
   168  
   169  ## Providing git config at execution
   170  
   171  You can provide git config through the `WithPushConfig` option to only take effect during the execution of a `Push`, removing the need to change config permanently.