README.md
1# Mergo
2
3A helper to merge structs and maps in Golang. Useful for configuration default values, avoiding messy if-statements.
4
5Also a lovely [comune](http://en.wikipedia.org/wiki/Mergo) (municipality) in the Province of Ancona in the Italian region of Marche.
6
7## Status
8
9It is ready for production use. [It is used in several projects by Docker, Google, The Linux Foundation, VMWare, Shopify, etc](https://github.com/imdario/mergo#mergo-in-the-wild).
10
11[![GoDoc][3]][4]
12[![GoCard][5]][6]
13[![Build Status][1]][2]
14[![Coverage Status][7]][8]
15[![Sourcegraph][9]][10]
16[](https://app.fossa.io/projects/git%2Bgithub.com%2Fimdario%2Fmergo?ref=badge_shield)
17
18[1]: https://travis-ci.org/imdario/mergo.png
19[2]: https://travis-ci.org/imdario/mergo
20[3]: https://godoc.org/github.com/imdario/mergo?status.svg
21[4]: https://godoc.org/github.com/imdario/mergo
22[5]: https://goreportcard.com/badge/imdario/mergo
23[6]: https://goreportcard.com/report/github.com/imdario/mergo
24[7]: https://coveralls.io/repos/github/imdario/mergo/badge.svg?branch=master
25[8]: https://coveralls.io/github/imdario/mergo?branch=master
26[9]: https://sourcegraph.com/github.com/imdario/mergo/-/badge.svg
27[10]: https://sourcegraph.com/github.com/imdario/mergo?badge
28
29### Latest release
30
31[Release v0.3.7](https://github.com/imdario/mergo/releases/tag/v0.3.7).
32
33### Important note
34
35Please keep in mind that in [0.3.2](//github.com/imdario/mergo/releases/tag/0.3.2) Mergo changed `Merge()`and `Map()` signatures to support [transformers](#transformers). An optional/variadic argument has been added, so it won't break existing code.
36
37If you were using Mergo **before** April 6th 2015, please check your project works as intended after updating your local copy with ```go get -u github.com/imdario/mergo```. I apologize for any issue caused by its previous behavior and any future bug that Mergo could cause (I hope it won't!) in existing projects after the change (release 0.2.0).
38
39### Donations
40
41If Mergo is useful to you, consider buying me a coffee, a beer or making a monthly donation so I can keep building great free software. :heart_eyes:
42
43<a href='https://ko-fi.com/B0B58839' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://az743702.vo.msecnd.net/cdn/kofi1.png?v=0' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a>
44[](https://beerpay.io/imdario/mergo)
45[](https://beerpay.io/imdario/mergo)
46<a href="https://liberapay.com/dario/donate"><img alt="Donate using Liberapay" src="https://liberapay.com/assets/widgets/donate.svg"></a>
47
48### Mergo in the wild
49
50- [moby/moby](https://github.com/moby/moby)
51- [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes)
52- [vmware/dispatch](https://github.com/vmware/dispatch)
53- [Shopify/themekit](https://github.com/Shopify/themekit)
54- [imdario/zas](https://github.com/imdario/zas)
55- [matcornic/hermes](https://github.com/matcornic/hermes)
56- [OpenBazaar/openbazaar-go](https://github.com/OpenBazaar/openbazaar-go)
57- [kataras/iris](https://github.com/kataras/iris)
58- [michaelsauter/crane](https://github.com/michaelsauter/crane)
59- [go-task/task](https://github.com/go-task/task)
60- [sensu/uchiwa](https://github.com/sensu/uchiwa)
61- [ory/hydra](https://github.com/ory/hydra)
62- [sisatech/vcli](https://github.com/sisatech/vcli)
63- [dairycart/dairycart](https://github.com/dairycart/dairycart)
64- [projectcalico/felix](https://github.com/projectcalico/felix)
65- [resin-os/balena](https://github.com/resin-os/balena)
66- [go-kivik/kivik](https://github.com/go-kivik/kivik)
67- [Telefonica/govice](https://github.com/Telefonica/govice)
68- [supergiant/supergiant](supergiant/supergiant)
69- [SergeyTsalkov/brooce](https://github.com/SergeyTsalkov/brooce)
70- [soniah/dnsmadeeasy](https://github.com/soniah/dnsmadeeasy)
71- [ohsu-comp-bio/funnel](https://github.com/ohsu-comp-bio/funnel)
72- [EagerIO/Stout](https://github.com/EagerIO/Stout)
73- [lynndylanhurley/defsynth-api](https://github.com/lynndylanhurley/defsynth-api)
74- [russross/canvasassignments](https://github.com/russross/canvasassignments)
75- [rdegges/cryptly-api](https://github.com/rdegges/cryptly-api)
76- [casualjim/exeggutor](https://github.com/casualjim/exeggutor)
77- [divshot/gitling](https://github.com/divshot/gitling)
78- [RWJMurphy/gorl](https://github.com/RWJMurphy/gorl)
79- [andrerocker/deploy42](https://github.com/andrerocker/deploy42)
80- [elwinar/rambler](https://github.com/elwinar/rambler)
81- [tmaiaroto/gopartman](https://github.com/tmaiaroto/gopartman)
82- [jfbus/impressionist](https://github.com/jfbus/impressionist)
83- [Jmeyering/zealot](https://github.com/Jmeyering/zealot)
84- [godep-migrator/rigger-host](https://github.com/godep-migrator/rigger-host)
85- [Dronevery/MultiwaySwitch-Go](https://github.com/Dronevery/MultiwaySwitch-Go)
86- [thoas/picfit](https://github.com/thoas/picfit)
87- [mantasmatelis/whooplist-server](https://github.com/mantasmatelis/whooplist-server)
88- [jnuthong/item_search](https://github.com/jnuthong/item_search)
89- [bukalapak/snowboard](https://github.com/bukalapak/snowboard)
90
91## Installation
92
93 go get github.com/imdario/mergo
94
95 // use in your .go code
96 import (
97 "github.com/imdario/mergo"
98 )
99
100## Usage
101
102You can only merge same-type structs with exported fields initialized as zero value of their type and same-types maps. Mergo won't merge unexported (private) fields but will do recursively any exported one. It won't merge empty structs value as [they are not considered zero values](https://golang.org/ref/spec#The_zero_value) either. Also maps will be merged recursively except for structs inside maps (because they are not addressable using Go reflection).
103
104```go
105if err := mergo.Merge(&dst, src); err != nil {
106 // ...
107}
108```
109
110Also, you can merge overwriting values using the transformer `WithOverride`.
111
112```go
113if err := mergo.Merge(&dst, src, mergo.WithOverride); err != nil {
114 // ...
115}
116```
117
118Additionally, you can map a `map[string]interface{}` to a struct (and otherwise, from struct to map), following the same restrictions as in `Merge()`. Keys are capitalized to find each corresponding exported field.
119
120```go
121if err := mergo.Map(&dst, srcMap); err != nil {
122 // ...
123}
124```
125
126Warning: if you map a struct to map, it won't do it recursively. Don't expect Mergo to map struct members of your struct as `map[string]interface{}`. They will be just assigned as values.
127
128More information and examples in [godoc documentation](http://godoc.org/github.com/imdario/mergo).
129
130### Nice example
131
132```go
133package main
134
135import (
136 "fmt"
137 "github.com/imdario/mergo"
138)
139
140type Foo struct {
141 A string
142 B int64
143}
144
145func main() {
146 src := Foo{
147 A: "one",
148 B: 2,
149 }
150 dest := Foo{
151 A: "two",
152 }
153 mergo.Merge(&dest, src)
154 fmt.Println(dest)
155 // Will print
156 // {two 2}
157}
158```
159
160Note: if test are failing due missing package, please execute:
161
162 go get gopkg.in/yaml.v2
163
164### Transformers
165
166Transformers allow to merge specific types differently than in the default behavior. In other words, now you can customize how some types are merged. For example, `time.Time` is a struct; it doesn't have zero value but IsZero can return true because it has fields with zero value. How can we merge a non-zero `time.Time`?
167
168```go
169package main
170
171import (
172 "fmt"
173 "github.com/imdario/mergo"
174 "reflect"
175 "time"
176)
177
178type timeTransfomer struct {
179}
180
181func (t timeTransfomer) Transformer(typ reflect.Type) func(dst, src reflect.Value) error {
182 if typ == reflect.TypeOf(time.Time{}) {
183 return func(dst, src reflect.Value) error {
184 if dst.CanSet() {
185 isZero := dst.MethodByName("IsZero")
186 result := isZero.Call([]reflect.Value{})
187 if result[0].Bool() {
188 dst.Set(src)
189 }
190 }
191 return nil
192 }
193 }
194 return nil
195}
196
197type Snapshot struct {
198 Time time.Time
199 // ...
200}
201
202func main() {
203 src := Snapshot{time.Now()}
204 dest := Snapshot{}
205 mergo.Merge(&dest, src, mergo.WithTransformers(timeTransfomer{}))
206 fmt.Println(dest)
207 // Will print
208 // { 2018-01-12 01:15:00 +0000 UTC m=+0.000000001 }
209}
210```
211
212
213## Contact me
214
215If I can help you, you have an idea or you are using Mergo in your projects, don't hesitate to drop me a line (or a pull request): [@im_dario](https://twitter.com/im_dario)
216
217## About
218
219Written by [Dario Castañé](http://dario.im).
220
221## Top Contributors
222
223[](https://sourcerer.io/fame/imdario/imdario/mergo/links/0)
224[](https://sourcerer.io/fame/imdario/imdario/mergo/links/1)
225[](https://sourcerer.io/fame/imdario/imdario/mergo/links/2)
226[](https://sourcerer.io/fame/imdario/imdario/mergo/links/3)
227[](https://sourcerer.io/fame/imdario/imdario/mergo/links/4)
228[](https://sourcerer.io/fame/imdario/imdario/mergo/links/5)
229[](https://sourcerer.io/fame/imdario/imdario/mergo/links/6)
230[](https://sourcerer.io/fame/imdario/imdario/mergo/links/7)
231
232
233## License
234
235[BSD 3-Clause](http://opensource.org/licenses/BSD-3-Clause) license, as [Go language](http://golang.org/LICENSE).
236
237
238[](https://app.fossa.io/projects/git%2Bgithub.com%2Fimdario%2Fmergo?ref=badge_large)
239
){kind=link}
){kind=link}
){kind=link}
){kind=link}