https://github.com/p403n1x87/git-railway

🚂💨✨ Visualise local git branches as neat interactive HTML pages
https://github.com/p403n1x87/git-railway

Last synced: 6 months ago
JSON representation

🚂💨✨ Visualise local git branches as neat interactive HTML pages

• Host: GitHub
• URL: https://github.com/p403n1x87/git-railway
• Owner: P403n1x87
• License: gpl-3.0
• Created: 2020-10-01T16:58:00.000Z (about 5 years ago)
• Default Branch: main
• Last Pushed: 2020-12-03T19:05:19.000Z (almost 5 years ago)
• Last Synced: 2025-04-12T16:59:11.238Z (6 months ago)
• Language: Python
• Size: 356 KB
• Stars: 14
• Watchers: 3
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE.md

Awesome Lists containing this project

README

          
Git Railway


Visualise local git branches as neat interactive HTML pages




  

      

  

      

  





  

	

    

  

  

  

    

  

  

    

  





  

  Installation •

  Usage •

  Details

	

  





	



# Installation

Git Railway is available from PyPI

~~~

pipx install git-railway

~~~

# Usage

Navigate to a git repository, or any sub-folder, and run

~~~ shell

git-railway

~~~

Your railway graph will be generated in `railway.html`. Use the `-o` or

`--output` option to override the default location, e.g.

~~~ shell

git-railway --output /tmp/mytemprailwaygraph.html

~~~

## Remote Branches

If you want to include all the remote branches to the railway graph, you can

pass the `-a` or `--all` option, e.g.

~~~ shell

git-railway --all

~~~

## GitHub References

If 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 `--gh` option, e.g.

~~~ shell

git-railway --gh p403n1x87/git-railway

~~~

## Scaling

You can control the size of the generated railway graph by setting the scaling

factor with the `-s` or `--scale` option, e.g.

~~~ shell

git-railway -s 1.5

~~~

This will make the SVG 50% larger than normal.

## Verbosity

You can also control the amount of information to include using the `-v` or

`--verbose` option. If you switch this on, the railway graph will inline the

commit summary for easier navigation.

~~~ shell

git-railway -v

~~~



	



## Conventional Commits

If you're into the habit of using the [Conventional Commits] format 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 a

_BREAKING CHANGE_ will have a different colour for easy identification.



	



# Details

## There's no such thing as *branch* in 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 the *actual* branch 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 ordering

To complicate things even more, there can be cases where a parent commit has a

timestamp which is in the *future* with 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 is

`O(n log n)`.

[Conventional Commits]: https://www.conventionalcommits.org