docs: def update(extract=False):
      '''
      Update the ports tree
  
      extract : False
          If ``True``, runs a ``portsnap extract`` after fetching, should be used
          for first-time installation of the ports tree.
  
      CLI Example:
  
      .. code-block:: bash
  
          salt '*' ports.update
      '''
      result = __salt__['cmd.run_all'](
          _portsnap() + ['fetch'],
          python_shell=False
      )
      if not result['retcode'] == 0:
          raise CommandExecutionError(
              'Unable to fetch ports snapshot: {0}'.format(result['stderr'])
          )
  
      ret = []
      try:
          patch_count = re.search(
              r'Fetching (\d+) patches', result['stdout']
          ).group(1)
      except AttributeError:
          patch_count = 0
  
      try:
          new_port_count = re.search(
              r'Fetching (\d+) new ports or files', result['stdout']
          ).group(1)
      except AttributeError:
          new_port_count = 0
  
      ret.append('Applied {0} new patches'.format(patch_count))
      ret.append('Fetched {0} new ports or files'.format(new_port_count))
  
      if extract:
          result = __salt__['cmd.run_all'](
              _portsnap() + ['extract'],
              python_shell=False
          )
          if not result['retcode'] == 0:
              raise CommandExecutionError(
                  'Unable to extract ports snapshot {0}'.format(result['stderr'])
              )
  
      result = __salt__['cmd.run_all'](
          _portsnap() + ['update'],
          python_shell=False
      )
      if not result['retcode'] == 0:
          raise CommandExecutionError(
              'Unable to apply ports snapshot: {0}'.format(result['stderr'])
          )
  
      __context__.pop('ports.list_all', None)
      return '\n'.join(ret)