.. _bag-merge:
.. _tool-merge:

===========
 bag merge
===========

.. program:: bag merge

Synopsis
========

:samp:`bag merge {[OPTIONS]} -o {OUTPUT} {INPUT1} [{INPUT2} ...]`

Description
===========

Copy :term:`events <event>` from :term:`log files <log file>`
:samp:`{INPUT1}`, :samp:`{INPUT2}` etc. into a new :term:`log file`
:samp:`{OUTPUT}`.

.. seealso::

   :ref:`rsb:common-options`
     The usual RSB-related commandline options are accepted.

   :ref:`rsb:idl-options`
     The usual IDL-related commandline options are accepted.

   :ref:`replay-related-options`
     The usual replay-related commandline options are accepted.

.. option:: --output-file OUTPUT, -o OUTPUT

   Write transformed :term:`events <event>` into file
   :samp:`{OUTPUT}`. The file format is determined based on the file
   type (which is determined based on the file extension) of
   :samp:`{OUTPUT}`.

   .. Tip::

      The output of :option:`common --help-for` ``all`` includes a
      list of supported file formats.

.. option:: --index-timestamp NAME

   Use the timestamp named :samp:`{NAME}` to index :term:`events
   <event>` in the created :term:`log file`. The default is to keep
   the timestamp under which the :term:`event` was stored in the
   source :term:`log file`.

.. option:: --channel-allocation SPEC, -a SPEC

   When not supplied, recreate :term:`channels <channel>` of the input
   :term:`log files <log file>`. Otherwise, use the strategy
   designated by :samp:`{SPEC}` to create :term:`channels <channel>`
   in the output :term:`log file`. See :option:`bag record
   --channel-allocation` for details.

Examples
========

* .. code-block:: sh

     $ bag merge -o bla.tide '/vol/my-separate-logs/**/*.tide'

  The above command merges all :term:`log files <log file>` matching
  the glob expression :file:`/vol/my-separate-logs/**/*.tide` into a
  single :term:`log file` named :file:`bla.tide`.