class_docstr: Representation of a Git repository
  
      
docstr: Wrapper for `git for-each-ref`
  
  Please see manual page git-for-each-ref(1) for a complete overview
  of its functionality. Only a subset of it is supported by this
  wrapper.
  
  Parameters
  ----------
  fields : iterable or str
    Used to compose a NULL-delimited specification for for-each-ref's
    --format option. The default field list reflects the standard
    behavior of for-each-ref when the --format option is not given.
  pattern : list or str, optional
    If provided, report only refs that match at least one of the given
    patterns.
  points_at : str, optional
    Only list refs which points at the given object.
  sort : list or str, optional
    Field name(s) to sort-by. If multiple fields are given, the last one
    becomes the primary key. Prefix any field name with '-' to sort in
    descending order.
  count : int, optional
    Stop iteration after the given number of matches.
  contains : str, optional
    Only list refs which contain the specified commit.
  
  Yields
  ------
  dict with items matching the given `fields`
  
  Raises
  ------
  ValueError
    if no `fields` are given
  
  RuntimeError
    if `git for-each-ref` returns a record where the number of
    properties does not match the number of `fields`
docstr_tok: ["Wrapper","for","`","git","for-each-ref","`","Please","see","manual","page","git-for-each-ref","(","1",")","for","a","complete","overview","of","its","functionality",".","Only","a","subset","of","it","is","supported","by","this","wrapper",".","Parameters","--","--","--","--","--","fields",":","iterable","or","str","Used","to","compose","a","NULL-delimited","specification","for","for-each-ref's","--","format","option",".","The","default","field","list","reflects","the","standard","behavior","of","for-each-ref","when","the","--","format","option","is","not","given",".","pattern",":","list","or","str",",","optional","If","provided",",","report","only","refs","that","match","at","least","one","of","the","given","patterns",".","points_at",":","str",",","optional","Only","list","refs","which","points","at","the","given","object",".","sort",":","list","or","str",",","optional","Field","name","(","s",")","to","sort-by",".","If","multiple","fields","are","given",",","the","last","one","becomes","the","primary","key",".","Prefix","any","field","name","with","'-","'","to","sort","in","descending","order",".","count",":","int",",","optional","Stop","iteration","after","the","given","number","of","matches",".","contains",":","str",",","optional","Only","list","refs","which","contain","the","specified","commit",".","Yields","--","--","--","dict","with","items","matching","the","given","`","fields","`","Raises","--","--","--","ValueError","if","no","`","fields","`","are","given","RuntimeError","if","`","git","for-each-ref","`","returns","a","record","where","the","number","of","properties","does","not","match","the","number","of","`","fields","`"]
code: def for_each_ref_(
      self,
      fields=("objectname", "objecttype", "refname"),
      pattern=None,
      points_at=None,
      sort=None,
      count=None,
      contains=None,
  ):
      """Wrapper for `git for-each-ref`
  
      Please see manual page git-for-each-ref(1) for a complete overview
      of its functionality. Only a subset of it is supported by this
      wrapper.
  
      Parameters
      ----------
      fields : iterable or str
        Used to compose a NULL-delimited specification for for-each-ref's
        --format option. The default field list reflects the standard
        behavior of for-each-ref when the --format option is not given.
      pattern : list or str, optional
        If provided, report only refs that match at least one of the given
        patterns.
      points_at : str, optional
        Only list refs which points at the given object.
      sort : list or str, optional
        Field name(s) to sort-by. If multiple fields are given, the last one
        becomes the primary key. Prefix any field name with '-' to sort in
        descending order.
      count : int, optional
        Stop iteration after the given number of matches.
      contains : str, optional
        Only list refs which contain the specified commit.
  
      Yields
      ------
      dict with items matching the given `fields`
  
      Raises
      ------
      ValueError
        if no `fields` are given
  
      RuntimeError
        if `git for-each-ref` returns a record where the number of
        properties does not match the number of `fields`
      """
      if not fields:
          raise ValueError("no `fields` provided, refuse to proceed")
      fields = ensure_list(fields)
      cmd = [
          "for-each-ref",
          "--format={}".format(
              "%00".join("%({})".format(f) for f in fields)
          ),
      ]
      if points_at:
          cmd.append("--points-at={}".format(points_at))
      if contains:
          cmd.append("--contains={}".format(contains))
      if sort:
          for k in ensure_list(sort):
              cmd.append("--sort={}".format(k))
      if pattern:
          cmd += ensure_list(pattern)
      if count:
          cmd.append("--count={:d}".format(count))
  
      for line in self.call_git_items_(cmd, read_only=True):
          props = line.split("\0")
          if len(fields) != len(props):
              raise RuntimeError(
                  "expected fields {} from git-for-each-ref, but got: {}".format(
                      fields, props
                  )
              )
          yield dict(zip(fields, props))
  
imports: import logging
  import re
  import threading
  import time
  from contextlib import contextmanager
  from locale import getpreferredencoding
  from os import environ
  from os.path import lexists
  from typing import Optional
  from weakref import finalize, WeakValueDictionary
  from datalad.cmd import GitWitlessRunner, StdOutErrCapture
  from datalad.config import ConfigManager
  from datalad.dataset.repo import PathBasedFlyweight, RepoInterface, path_based_str_repr
  from datalad.runner.nonasyncrunner import STDERR_FILENO, STDOUT_FILENO
  from datalad.runner.protocol import GeneratorMixIn
  from datalad.runner.utils import AssemblingDecoderMixIn, LineSplitter
  from datalad.support.exceptions import CommandError, GitIgnoreError, InvalidGitRepositoryError, PathKnownToRepositoryError
  from datalad.utils import ensure_list, lock_if_required, Path
label_desc: Use image node_id 18 for calling the GitRepo obj's underlying member method code with example usage: obj.for_each_ref_(fields, pattern, points_at, sort, count, contains) without return types