Metadata-Version: 2.1
Name: githistorian
Version: 0.1.3
Summary: Graph visualizer for git history
Home-page: https://github.com/drachlyznardh/githistorian
Author: Ivan Simonini
Author-email: drachlyznardh@gmail.com
License: UNKNOWN
Description: githistorian
        =============
        
        Alternative layout for git log --graph, inspired by
        [this GIST thread](https://gist.github.com/datagrok/4221767).
        
        Dependencies
        ------------
        
         - bintrees 2.0.1
        
        Usage
        -----
        
        <command> [options] [target…]
        
        Displays the targets history. If no target is given, HEAD is selected. Each
        target is assigned its own column, in the specified order
        
        ### Options
        
        - -v, --verbose                 : prints some stats before showing history
        - -n<N>, --limit=<N>            : cuts the history at N commits
        - -p<format>, --pretty=<format> : format string, passed to `git log --pretty`
        - -a, --all, --heads            : appends all local branches to the target list
        - -t, --tags                    : appends all tags to the target list
        - -r, --remotes                 : appends all remote branches to the target list
        - -f<name>, --file<name>        : loads preferences from <name>
        
        Preferences
        -----------
        
        Preferences are loaded from the .githistorian file (or from the file specified
        by -f,--file) if present. This file can contain options and arguments, one per
        line. Command line arguments override those written on file.
        
        Invocation
        ----------
        
        Since 0.0-j, githistorian is a proper Python module, this it can be invoked as
        
        		python -m githistorian
        
        once it is installed on your system. You can test it before installation by
        
        		PYTHONPATH=src python -m githistorian
        
        or by simply calling make in this directory.
        
        Concept
        -------
        
        The long-term goal of this project is to provide an alternative layout for `git
        log --graph`; the short-term goal is to display the history of a Git repo using
        straight lines to represent long-lived branches. The user can specify how
        branches are ordered, thus having specific branches on specific columns.
        
        Proof of existence
        ------------------
        
        This whole project exists only to prove that a different, more readable layout
        for the graph of a repo is possible, and that I could actually write it. It is
        now fairly functional, but vastly slower than invoking Git itself and it is a
        standalone application.
        
        Implementation
        --------------
        
        It is a Python script, which queries the Git repo for all its history (commit
        relations) and crunches it to build a graph, then it spreads the commits on a
        grid and dumps it all on the terminal.
        
        ### Vertical spread
        
        Each line can contain but a single commit. No commit can be displayed before its
        child(ren), and no commit can displayed after its parent(s); commit with no
        relation at all (heads with completely independent chunks of history) appear in
        order, as specified.
        
        ### Horizontal spread
        
        Heads appear in order, as specified, or in alphabetical order by default.
        Commits in the same branch appear in the same column as long as there is no
        overlapping with arrows.
        
        Relationship between commit may be:
        
         - implied, when parent and child are directly one over the other, in the same
           column and in two consecutive rows;
         - highlighted with a vertical line, when parent and cihld are directly one over
           the other, but with one or more row in between them;
         - highlighted with an arrow, which moves horizontally (left or right) from the
           parent until it reaches the child's column, bends at a right angle and moves
           up until it reaches the child
        
        ### Display
        
        Each commit is displayed as a white bullet character '⬤' (\u2022). Arrows take
        the color of their destination column and are drawn with unicode box chars.
        
        As each merge commit receives all its incoming arrows from the bottom, there is
        no indication of the original order of parents. You cannot infere which parent
        was merged into which, as the relative row and column of each parent depends on
        the whole layout.
        
        At the end of its row, each commit is resented with its equivalent `git show -s
        --pretty='<format>' ` output. You can specify the format string with options `-p,
        --pretty`, otherwise my own default will be used instead.
        
        Due to the cut at N commits, some merge commits may loose some children. To
        prevent the drawing from missing these relation, cut commits are replaced with
        placeholders. These fake nodes do not have children, they do not display a
        message and they have no label. A special '[…]' marker appears beside their
        bullet.
        
        Testing
        -------
        
        For testing, I used a bunch of repos. First, this one; in addition, I built a
        series of artificial repos with different histories, to check the behaviour with
        octopus merges, crossing branches, multiple heads, multiple bases, a copy of the
        git-flow sample image.
        
        I tested it against some other projects of mine, and also against the Git repo
        itself (commit 96db324a73fdada6fbe7b63221986f8f18cc63b0): it took almost 6m to
        render 146M of text with ~37k rows and 632 columns, but it worked. Version 0.1
        took 5m27.876s to do the same.
        
        TODO
        ====
        
        **Display options**: the layout could be mirrored both vertically and
        horizontally, the charset could be different (for those terminals / fonts
        without full unicode support), colors could be optional, there could be more
        colors (with fade and bold modes, or with full 256 color if supported), map-only
        display mode could ignore any non-merge / non-fork commit…
        
        **Efficency**: there are no intermediate steps in the layout computation, no
        checkpoints, no nothing. Even with no change in the repo, each invocation must
        read the whole history, rebuild the graph and recompute the column for each
        commit. I am not sure how I could keep the graph in memory (or on file) and add
        a single commit (or arrow) to it without starting from scratch.
        
        **Standalone**: there is no integration with Git, for a number of reasons.
        
         - Git integration is hard. I have been using Git for years, but I have no
           experience with its source, its internal structure and its community. I took
           a look at the graph's sourcecode and then I ran away;
         - I don't know what I want, nor what people would like; the GIST thread I
           mentioned as inspiration gave me some ideas, but many more details need to be
           established before the project “gets serious”;
         - the resulting layout takes a very wide space to display, much more than the
           default Git graph; this whole project may be nearly-unusable on repos with
           very long histories, or with a great deal of open branches;
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
