Package: git-railway
Git RailwayVisualise local git branches as neat interactive HTML pagesInstallation•Usage•DetailsInstallationGit Railway is available from PyPIpipx install git-railwayUsageNavigate to a git repository, or any sub-folder, and rungit-railwayYour railway graph will be generated inrailway.html. Use the-oor--outputoption to override the default location, e.g.git-railway--output/tmp/mytemprailwaygraph.htmlRemote BranchesIf you want to include all the remote branches to the railway graph, you can
pass the-aor--alloption, e.g.git-railway--allGitHub ReferencesIf the remote repository is hosted on GitHub, issue and PR
references are replaced with actual links. If the GitHub slug derived from the
remotes is wrong, you can override it with the--ghoption, e.g.git-railway--ghp403n1x87/git-railwayScalingYou can control the size of the generated railway graph by setting the scaling
factor with the-sor--scaleoption, e.g.git-railway-s1.5This will make the SVG 50% larger than normal.VerbosityYou can also control the amount of information to include using the-vor--verboseoption. If you switch this on, the railway graph will inline the
commit summary for easier navigation.git-railway-vConventional CommitsIf you're into the habit of using theConventional Commitsformat for your
commit messages, the popup window that appears when you hover over a commit will
highlight that information for you. Additionally, commits that are marked as aBREAKING CHANGEwill have a different colour for easy identification.DetailsThere's no such thing asbranchin Git!As you probably know already, a branch in git is a mere reference (or label)
that moves with every new commit. As such, it's hard if not impossible to
reconstruct theactualbranch from the information available from within a git
repository. This tools works by looking at the current local refs and collecting
all the commits that can be reached from them. The "branches" are the
reconstructed "best effort" by looking at the reflog to determine on which
commit a certain ref has been on. Sometimes this information is missing. For
example, when one does a merge by fast-forwarding, all the intermediate commits
are not marked with the ref of the target branch. Should they be part of the
branch or not? Whenever you see a piece of grey rail in the graph, that's where
the ref information is missing.Chrono-topological orderingTo complicate things even more, there can be cases where a parent commit has a
timestamp which is in thefuturewith respect to some of its children. Hence,
the trivial chronological ordering does not always work. Furthermore, one can
also have precision issues; if one creates multiple commits in quick succession,
they are likely to end up having the same timestamp. Topological order, on the
other hand, is not optimal either in its own. For what if we have some stale
branches that were never merged? They might end up at the very top of the graph,
even though its commits are quite old.The solution is a mix of chronological and topological sorting. For example, we
can start by sorting all the commits based on their timestamp, and then make
some changes to Kahn's algorithm to ensure that we position oldest commits
first. With the chronological sorting step at the beginning, the complexity isO(n log n).