Need help with deep_merge?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

139 Stars 54 Forks MIT License 68 Commits 14 Opened issues


Recursive Merging for Ruby Hashes

Services available


Need anything else?

Contributors list

DeepMerge Overview

Deep Merge is a simple set of utility functions for Hash. It permits you to merge elements inside a hash together recursively. The manner by which it does this is somewhat arbitrary (since there is no defining standard for this) but it should end up being pretty intuitive and do what you expect.

You can learn a lot more about this by reading the test file. It's pretty well documented and has many examples of various merges from very simple to pretty complex.

The primary need that caused me to write this library is the merging of elements coming from HTTP parameters and related stored parameters in session. This lets a user build up a set of parameters over time, modifying individual items.

Deep Merge Core Documentation

method permits merging of arbitrary child elements. The two top level elements must be hashes. These hashes can contain unlimited (to stack limit) levels of child elements. These child elements to not have to be of the same types. Where child elements are of the same type,
will attempt to merge them together. Where child elements are not of the same type,
will skip or optionally overwrite the destination element with the contents of the source element at that level. So if you have two hashes like this:
source = {:x => [1,2,3], :y => 2}
dest =   {:x => [4,5,'6'], :y => [7,8,9]}
Results: {:x => [1,2,3,4,5,'6'], :y => 2}

By default,

will overwrite any unmergeables and merge everything else. To avoid this, use
(no bang/exclamation mark)


Options are specified in the last parameter passed, which should be in hash format:

hash.deep_merge!({:x => [1,2]}, {:knockout_prefix => '--'})
:preserve_unmergeables  DEFAULT: false
  Set to true to skip any unmergeable elements from source
:knockout_prefix        DEFAULT: nil
  Set to string value to signify prefix which deletes elements from existing element
:overwrite_arrays       DEFAULT: false
  Set to true if you want to avoid merging arrays
:sort_merged_arrays     DEFAULT: false
  Set to true to sort all arrays that are merged together
:unpack_arrays          DEFAULT: nil
  Set to string value to run "Array::join" then "String::split" against all arrays
:merge_hash_arrays      DEFAULT: false
  Set to true to merge hashes within arrays
:extend_existing_arrays DEFAULT: false
  Set to true to extend existing arrays, instead of overwriting them
:merge_nil_values       DEFAULT: false
  Set to true to merge nil hash values, overwriting a possibly non-nil value
:merge_debug            DEFAULT: false
  Set to true to get console output of merge process for debugging

Selected Options Details


The purpose of this is to provide a way to remove elements from existing Hash by specifying them in a special way in incoming hash

source = {:x => ['--1', '2']}
dest   = {:x => ['1', '3']}
Results: {:x => ['2','3']}

Additionally, if the knockout_prefix is passed alone as a string, it will cause the entire element to be removed:

source = {:x => '--'}
dest   = {:x => [1,2,3]}
Results: {:x => ""}

:overwrite_arrays The purpose of this is to provide a way to replace Arrays instead of having them merge together.

source = {:x => ['1', '2']}
dest   = {:x => ['3', '4']}
dest.deep_merge!(source, {:overwrite_arrays => true})
Results: {:x => ['1', '2']}

:unpack_arrays The purpose of this is to permit compound elements to be passed in as strings and to be converted into discrete array elements

irsource = {:x => ['1,2,3', '4']}
dest   = {:x => ['5','6','7,8']}
dest.deep_merge!(source, {:unpack_arrays => ','})
Results: {:x => ['1','2','3','4','5','6','7','8'}

Why: If receiving data from an HTML form, this makes it easy for a checkbox to pass multiple values from within a single HTML element


merge hashes within arrays

source = {:x => [{:y => 1}]}
dest   = {:x => [{:z => 2}]}
dest.deep_merge!(source, {:merge_hash_arrays => true})
Results: {:x => [{:y => 1, :z => 2}]}


Push src elements to existing arrays, instead of overwriting them.

source = { "property" => "4" }
dest   = { "property" => ["1", "2", "3"] }
dest.deep_merge!(source, {:extend_existing_arrays => true})
Results: {"property" => ["1", "2", "3", "4"]}


The purpose of this option is to allow nil hash values to be merged. The prior behavior was to discard nil hash values and remains the default if not specified.

source = {"item" => nil}
dest   = {"item" => "existing"}
dest.deep_merge!(source, {:merge_nil_values => true})
Results: {"item" => nil}

There are many tests for this library - and you can learn more about the features and usages of deep_merge! by just browsing the test examples.

Using deep_merge in Rails

To avoid conflict with ActiveSupport, load deep_merge via:

require 'deep_merge/rails_compat'

In a Gemfile:

gem "deep_merge", :require => 'deep_merge/rails_compat'

The deep_merge methods will then be defined as


Simple Example Code

require 'deep_merge'
x = {:x => [3,4,5]}
y = {:x => [1,2,3]}
# results: y = {:x => [1,2,3,4,5]}


was written by Steve Midgley, and is now maintained by Daniel DeLeo. The official home of
on the internet is now

Copyright (c) 2008-2016 Steve Midgley, released under the MIT license

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.