Looks like if I call setMetadata on an object, it merges the data with what's in production...

var bucket = ...; // Get a bucket somehow.
var file = bucket.file('my-file');

file.setMetadata({
  metadata: {
    first: 'first'
  }
});

file.setMetadata({
  metadata: {
    second: 'second'
  }
}, function(err, metadata) {
  // metadata here is {first: 'first', second: 'second'}
  // Expected it to be just {second: 'second'} ....
});

I suspect that we can't .. fix this all that much... but maybe we can at least document it ?

The options we have so far:

• Make metadata immutable: remove setMetadata
• Operate on a single attribute at a time: getMetadata(key) and setMetadata(key, value)
• Rename setMetadata to patchMetadata or mergeMetadata
• Add some documentation about the behavior of setMetadata

/cc @Capstan @aozarov