retronym / git-what-branch Goto Github PK

NAME
    git-what-branch - Discover what branch a particular commit was made on
    or near

SYNOPSIS
    git-what-branch [[--branches] | [--allbranches] | [--tags] | [--allref]]
    [--first-parent] [--first-parent-simple] [--all] [--topo-order |
    --date-order ] [--quiet] [--reference=reference,reference,reference]
    <commit-hash/tag>...

OVERVIEW
    Tell us (by default) the earliest causal path of commits and merges to
    cause the requested commit got onto a named branch. If a commit was made
    directly on a named branch, that obviously is the earliest path.

    By earliest causal path, we mean the path which merged into a named
    branch the earliest, by commit time (unless --topo-order is specified).

    You may specify a particular reference branch or tag or revision to look
    at instead of searching (by default) the path for all named branches.
    Searching the path for all named branches can take a long time for an
    early commit occurring on many branches. If you specifically name a
    reference branch or commit, it should normally take seconds.

DESCRIPTION
  --branches
    The default mode of check the path to any local branch.

  --allbranches
    Check the path to any local or remote branch.

  --tags
    Check the path to any known tags

  --allref
    Check the path to any local or remote branch and to any tag.

  --all
    If the commit in question was not made directly on a named branch (in
    which case all branch names would be printed), the system picks the
    named branch which the commit was merged to first and prints only that
    path. With this argument all paths from the commit in question to all
    named branches that it was committed onto are printed.

  --first-parent
    If the commit in question was not made directly on a named branch, fail.
    If the commit was made directly on a named branch, print the branch name
    or names.

  --first-parent-simple
    Same as --first-parent except instead of outputting in the "(aka)"
    format if there are multiple differently spelled but otherwise identical
    branches, print all directly reachable branches/references out with one
    line per branch/reference.

  --topo-order
    Instead of selecting the merge path which resulted in the earliest
    commit to a named branch, select the merge path which resulted in the
    fewest merges. If multiple merge paths have the same distance, use
    earliest merge to break ties.

  --date-order
    The default ordering where the merge path which resulted in the earliest
    commit to a named branch is displayed.

  --quiet
    If the commit was not made on a branch, do not print the path from the
    commit to the named branch, just print the branch name.

  --reference <tagname/commithash/branchname>
    Instead of auto-generating the list of branches/tags to check to see how
    the commit in question got there, specify the (comma seperated) list of
    tags, branch names, commits, or other references that this program
    should use to try and find minimal and early paths to from the command
    line references.

PERFORMANCE
    If many branches (e.g. hundreds) contain the commit, the system may take
    a long time (for a particular commit in the linux tree, it took 8 second
    to explore a branch, but there were over 200 candidate branches) to
    track down the path to each commit. Selection of a particular
    --reference-branch --reference tag to examine will be hundreds of times
    faster (if you have hundreds of candidate branches).

EXAMPLES
     # git-what-branch --all 1f9c381fa3e0b9b9042e310c69df87eaf9b46ea4
     v2.6.12-rc3-450-g1f9c381 used the following minimal temporal path:
       merged to v2.6.12-rc3-461-g84e48b6 @Tue May  3 18:27:24 2005
       merged to v2.6.12-rc3-590-gbfd4bda @Thu May  5 08:59:37 2005
       v2.6.12-rc3-590-gbfd4bda is on v2.6.12-n
       v2.6.12-rc3-590-gbfd4bda is on v2.6.12-rc4-n
       [...]
       v2.6.12-rc3-590-gbfd4bda is on v2.6.36-rc4-n
       v2.6.12-rc3-590-gbfd4bda is on v2.6.36-rc5-n(aka master)

BUGS
    git fast-forward merges make changes to branches without reflecting that
    history in a merge commit. This means that when later reviewing that
    history, git may label (via --first-parent) the wrong branch as being
    named a specific name. Any lies which git makes are reflected in the
    output of this program.

    Branches which are created after the commit you are interested in has
    been merged into another named branch you are interested in cannot be
    distinguished from the original branch. Example if you have master
    branch, you make commit A, then make a release branch named v1.0, after
    branch v1.0 has been created there is no way to know that v1.0 was
    created later and so both branches will be listed as the branches that
    commit A was made on. If git recorded when a branch was created, we
    could avoid this problem.

    If multiple branches (say due to the previous bug) are candidates and
    the commit was NOT made directly on a named branch but rather on an
    anonymous branch that was merged, unless you request --all, a
    pseudo-random branch will be chosen as the branch advertised via the
    merge path.

    This program does not take into account the effects of cherry-picking
    the commit of interest, only merge operations.

ACKNOWLEDGMENTS
    Thanks to Artur Skawina for his assistance in developing some of the
    algorithms used by this script.

COPYRIGHT/LICENSE
    License: GPL v2 Copyright (c) 2010 Seth Robertson