        Update the current, specified or all topic branches with respect
        to changes in the branches they depend on and remote branches.
        This is performed in two phases -- first, changes within the
        dependencies are merged to the base, then the base is merged
        into the topic branch.  The output will guide you on what to do
        next in case of conflicts.

        You have enabled `git rerere` haven't you?

        Remember the default expiration time for resolved merge conflicts is
        only 60 days.  Increase their longevity by setting the Git
        configuration variable `gc.rerereResolved` to a higher number such
        as `9999` like so:

                git config --global gc.rerereResolved 9999

        The `--[no-]auto[-update]` options together with the
        `topgit.setAutoUpdate` config item control whether or not TopGit
        will automatically temporarily set `rerere.autoUpdate` to true while
        running `tg update`.  The default is true.  Note that this does not
        enable Git's `rerere` feature, it merely makes it automatically stage
        any previously resolved conflicts.  The `rerere.enabled` setting must
        still be separately enabled (i.e. set to `true`) for the `rerere`
        feature to do anything at all.

        Using `--auto[-update]` makes `tg update` always temporarily set
        `rerere.autoUpdate` to `true` while running `tg update`.  The
        `--no-auto[-update]` option prevents `tg update` from changing the
        `rerere.autoUpdate` setting, but if `rerere.autoUpdate` has already
        been enabled in a config file, `tg update` never disables it even
        with `--no-auto`.  If `topgit.setAutoUpdate` is unset or set to
        `true` then `tg update` implicitly does `--auto`, otherwise it
        does `--no-auto`.  An explicit command line `--[no-]auto[-update]`
        option causes the `topgit.setAutoUpdate` setting to be ignored.

        When both `rerere.enabled` and `rerere.autoUpdate` are set to true
        then `tg update` will be able to automatically continue an update
        whenever `git rerere` resolves all the conflicts during a merge.
        This can be such a huge time saver.  That's why the default is to have
        TopGit automatically set `rerere.autoUpdate` to true while
        `tg update` is running (but remember, unless `rerere.enabled` has
        been set to `true` it won't make any difference).

        When `-a` (or `--all`) is specified, updates all topic branches
        matched by `<pattern>`'s (see `git help for-each-ref` for details),
        or all if no `<pattern>` is given.  Any topic branches with missing
        dependencies will be skipped entirely unless `--skip-missing` is
        specified.

        When `--skip-missing` is specified, an attempt is made to update topic
        branches with missing dependencies by skipping only the dependencies
        that are missing.  Caveat utilitor.

        When `--stash` is specified (or the `topgit.autostash` config
        value is set to `true`), a ref stash will be automatically created
        just before beginning updates if any are needed.  The `--no-stash`
        option may be used to disable a `topgit.autostash=true` setting.
        See the `tg tag` `--stash` option for details.

        After the update, the branch which was current at the beginning of the
        update is returned to.

        If your dependencies are not up-to-date, `tg update` will first
        recurse into them and update them.

        If a remote branch update brings in dependencies on branches
        that are not yet instantiated locally, you can either bring
        in all the new branches from the remote using
        `tg remote --populate`, or only pick out the missing ones using
        `tg create -r` (`tg summary` will point out branches with incomplete
        dependencies by showing an `!` next to them).  TopGit will attempt to
        instantiate just the missing ones automatically for you, if possible,
        when `tg update` merges in the new dependencies from the remote.

        Using the alternative `--base` mode, `tg update` will update
        the base of a specified `[BASE]` branch (which is a branch created
        by `tg create` using the `--base` option) to the specified
        committish (the second argument) and then immediately merge that into
        the branch itself using the specified message for the merge commit.
        If no message is specified on the command line, an editor will open.
        Unless `--force` is used the new value for the base must contain
        the old value (i.e. be a fast-forward update).  This is for safety.

        This mode makes updates to `[BASE]` branches quick and easy.

        When `tg update` has stopped as a result of a merge conflict,
        there are four possible ways to handle this situation:

            `tg update --continue`
                                Once the merge conflict has been resolved
                                and committed, this will resume the
                                `tg update` operation that was interrupted
                                by encountering the merge conflict.

            `tg update --abort`
                                This aborts the entire `tg update`
                                operation that led to the merge conflict
                                and undoes everything that's been changed
                                since that `tg update` started.  In other
                                words, after `tg update --abort` it's as
                                though the `tg update` that led to the
                                merge conflict was never executed at all.

            `tg update --skip`
                                This will attempt to resume the `tg update`
                                operation that was interrupted by encountering
                                the merge conflict by skipping the current
                                branch that's being updated that encountered
                                the merge conflict.  The branch causing the
                                merge conflict will still be out-of-date (since
                                it's skipped by this command) and can still be
                                updated by a future `tg update` command.

            `tg update --stop`
                                This stops the `tg update` that's been
                                interrupted by the merge conflict by simply
                                removing the tg-update-in-progress state.
                                Everything else will be *left as-is!*  In other
                                words, if there's a current unresolved merge
                                conflict, it will still be present.  The
                                `HEAD` state may be detached, etc. etc.
                                Use of `tg update --stop` is not generally
                                helpful except in unusual circumstances.

        | TODO: `tg update -a -c` to autoremove (clean) up-to-date branches

