Giter Club home page Giter Club logo

visual-git-guide's Introduction

A Visual Git Reference

The goal of this website is to be a concise, visual reference for how git commands work. I often draw pictures like this on a whiteboard for my colleagues, so I figured I would make a nice electronic version once and for all.

Implementation

I chose to draw the images using TeX and PGF/TikZ. I originally tried using Graphviz, but unfortunately there is no way to tell it how to lay out the graph exactly. Using TikZ, I was able to create a domain-specific language to represent commit graphs, and I think the result turned out quite well.

All of the common macros are stored in common.tex. Each image source includes this file. To see an example of how to use these macros, look at commit-main.tex.

To generate the image files, I first create PDFs using pdflatex, and from there I create SVGs and PNGs using pdf2svg and convert, respectively.

Building from Source

First, the following must be installed:

sudo apt-get install make texlive-base texlive-fonts-extra pdf2svg imagemagick ghostscript

Then, build the images:

make

The result is in the ./build directory.

Pushing to gh-pages

Done via GitHubActions (.github/workflows/publish.yaml).

License

Copyright © 2010, Mark Lodato. Japanese translation © 2010, Kazu Yamamoto. Korean translation © 2011, Sean. Russian translation © 2012, Alex Sychev. French translation © 2012, Michel Lefranc. Chinese translation © 2012, wych. Spanish translation © 2012, Lucas Videla. Italian translation © 2012, Daniel Londero. German translation © 2013, Martin Funk, © 2017, Mirko Westermeier. Vietnamese translation © 2013, Hoat Le. Slovak translation © 2013, Ľudovít Lučenič. Portuguese translation © 2014, Gustavo de Oliveira. Traditional Chinese translation © 2015, Peter Dave Hello. Polish translation © 2017, Emil Wypych.

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 United States License.

visual-git-guide's People

Contributors

anishkny avatar arthurchenjs avatar delucas avatar dlondero avatar ewypych avatar fanweixiao avatar gentoid avatar goliveira avatar hoatle avatar idealhack avatar kant avatar kazu-yamamoto avatar lebigot avatar lethee avatar llucenic avatar mafulafunk avatar marklodato avatar memowe avatar michaelpereira avatar michel-lefranc avatar peterdavehello avatar rockhong avatar sevaorlov avatar vloginova avatar wych42 avatar yangl avatar yongsungyoon avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

visual-git-guide's Issues

Dark Mode for Web Site

VGG is my first port of call for remembering git commands, thanks for producing it!

One problem...most of my coding is done in the evening and I'm using dark mode for everything.

The VGG website is bright white. Most white websites I feed through the Dark Reader Chrome extension, but VGG isn't usable with Dark Reader, the black text on the arrows in the pictures doesn't get picked up, they stay black on a dark background (see picture, it's the best I could get it with manual tuning of Dark Reader), SVG or non-SVG is the same.

Would it be possible to have a dark mode on the website or change the text so that it works with Dark Reader?

Thank for reading!

image

Tikz vs metapost

Have you considered using metapost, for this project is implemented using tikz? I am in doubt which one I shall go for.

add explanation of yellow rectangle to Conventions section

In section "commit" there is a yellow rectangle highlighting a commit (presumably the one was just created by a command). It would be great to mention this graphic convention in section "Conventions".

PS: Thanks a lot for this guide, it is indispensable for me to understand some concepts for which words are too ambiguous (rebase [--onto] ...).

Can't use with Beamer

Thank you for sharing your code ! It's really useful for teaching GIT !

I wanted to put your TikZ code in a beamer presentation and got an error which is puzzling me.

My minimal working example:

%\documentclass[12pt]{article}
\documentclass{beamer}
\usepackage[latin1]{inputenc}
\usepackage{cmbright}
\usepackage[pdftex,margin=0pt,noheadfoot]{geometry}
\usepackage{tikz}
\usetikzlibrary{shapes,arrows,shadows,positioning,calc}

\colorlet{HEAD}{gray!50}
\colorlet{branch}{orange!50}
\colorlet{commit}{green!50}
\colorlet{index}{blue!40}
\colorlet{work}{red!40}
\colorlet{old HEAD}{HEAD!50}
\colorlet{old branch}{branch!50}

% Global Scaling Factors
% Values that seem reasonable:
%        1cm /  1pt / \Large
%       .5cm / .5pt / \scriptsize
\newlength\g
\setlength\g{1cm}
\newlength\gLine
\setlength\gLine{1pt}
\newcommand\gFont{\Large}

\geometry{papersize={24\g,14\g}}

\tikzset{
index/.style={rectangle, text width=5\g, text centered, rounded corners,
    minimum height=1.5\g, line width=3\gLine, fill=#1!50, draw=#1},
index/.default={index},
history/.style={index=commit, fill=commit!40},
work/.style={index=work},
%
object/.style={rectangle, text width=2\g, text centered, rounded corners,
    minimum height=1\g, line width=3\gLine, fill=#1!50, draw=#1},
object/.default={red},
commit/.style={object=commit, fill=commit!40},
new commit/.style={commit, double shadow},
branch/.style={object=branch},
HEAD/.style={object=HEAD},
old branch/.style={object=old branch, text=black!30},
old HEAD/.style={object=old HEAD, text=black!30},
attached HEAD/.style={HEAD, minimum height=2\g},
attached HEAD label/.style={object, draw=none, fill=none},
old attached HEAD/.style={old HEAD, minimum height=2\g},
old attached HEAD label/.style={attached HEAD label, text=black!30},
%
double shadow/.style={
    preaction={fill=#1,transform canvas={xshift=.2\g,yshift=-.2\g}},
    preaction={fill=#1,transform canvas={xshift=-.2\g,yshift=.2\g}},
    },
double shadow/.default={yellow!75},
%
line/.style={>=stealth', line width=1.5\gLine, draw=black!70, auto=right,
    bend right},
object line/.style={>=stealth, line width=1.5\gLine},
commit line/.style={object line, color=commit},
new commit line/.style={commit line},
HEAD line/.style={object line, color=HEAD},
branch line/.style={object line, color=branch},
old HEAD line/.style={object line, color=old HEAD},
old branch line/.style={object line, color=old branch},
cancel ref/.style={cross out, draw=black!70, line width=1\gLine},
%
background line/.style={draw=white, line width=6\gLine,
    shorten >=6\gLine, shorten <=6\gLine},
%
cmd/.style={color=black, font={\gFont\ttfamily}},
%
main/.style={node distance=.7\g, bend angle=35, font={\gFont},
    x=1.5\g, y=1.5\g},
every edge/.style={draw, ->},
}

\pgfdeclarelayer{HEAD}
\pgfsetlayers{HEAD,main}

\newcommand\boundingbox{\clip (-.5\textwidth,-.5\textheight) rectangle
    (.5\textwidth,.5\textheight);}

\newcommand\historynode[1][0,.5]{\node [history] (head) at (#1) {History};}
\newcommand\indexnode[1][0,-1]{\node [index] (index) at (#1) {Stage (Index)};}
\newcommand\worknode[1][0,-2.5]{\node [work] (work) at (#1) {Working Directory};}
\newcommand\normalcommits[1][-6,.75]{
    \commitTerminal cT at (#1);
    \commit a47c3 (A) -> cT;
    \commit b325c (B) -> A;
    \commit c10b9 (C) -> B;
    \commit da985 (D) -> C;
    \commit ed489 (E) -> D;
}
\newcommand\usualsetup{
    \normalcommits
    \indexnode
    \worknode
}

\def\ref [#1] "#2" : #3 -> #4;{
    \node [#1, above=.4\g of #4] (#3) {#2};
    \path [#1 line] (#3) edge (#4);
    }
\def\oldref [#1] "#2" : #3 -> #4;{
    \ref [old #1] "#2" : old #3 -> #4;
    \node [cancel ref, above=.2\g of #4, anchor=center] {};
    }
\def\refbelow [#1] "#2" : #3 -> #4;{
    \node [#1, below=.4\g of #4] (#3) {#2};
    \path [#1 line] (#3) edge (#4);
    }

\newcounter{tmp}
\def\commitTerminal #1 at (#2);{
    \node (#1) at (#2) {\LARGE$\cdots$};
    \pgfkeys{/child count/#1/.initial=0}
}
\def\commitcommon [#1] #2 (#3) -> [#4] #5;{
    \setcounter{tmp}{\pgfkeysvalueof{/child count/#5}}
    \node [#1, anchor=west] (#3) at ($ (#5.east) + (.5,\value{tmp}) $) {#2};
    \draw [#4] (#3) edge (#5);
    \addtocounter{tmp}{1}
    \pgfkeys{/child count/#3/.initial=0}
    \pgfkeys{/child count/#5=\value{tmp}}
}
\def\commit #1 (#2) -> #3;{\commitcommon [commit] #1 (#2) -> [commit line] #3;}
\def\newcommit #1 (#2) -> #3;{\commitcommon [new commit] #1 (#2) ->
[new commit line] #3;}

\def\branch #1 -> #2;{\ref [branch] "#1" : #1 -> #2;}
\def\oldbranch #1 -> #2;{\oldref [branch] "#1" : #1 -> #2;}

\def\addHEAD [#1] "#2" : #3 -> #4;{
    \begin{pgfonlayer}{HEAD}
        \node [#1, anchor=south] (#3) at (#4.south) {};
        \node [#1 label, anchor=south] (#3 label) at ($(#4.north)+(0,-3\gLine) 
        $) {#2};
    \end{pgfonlayer}
}
\def\addHEADbelow [#1] "#2" : #3 -> #4;{
    \begin{pgfonlayer}{HEAD}
        \node [#1, anchor=north] (#3) at (#4.north) {};
        \node [#1 label, anchor=north] (#3 label) at ($(#4.south)+(0,3\gLine) 
        $) {#2};
    \end{pgfonlayer}
}


\def\HEAD -> #1;{\addHEAD [attached HEAD] "HEAD" : HEAD -> #1;}
\def\oldHEAD -> #1;{\addHEAD [old attached HEAD] "HEAD" : old HEAD -> #1;}

\def\detachedHEAD -> #1;{\ref [HEAD] "HEAD" : HEAD -> #1;}
\def\olddetachedHEAD -> #1;{\oldref [HEAD] "HEAD" : HEAD -> #1;}

\pagestyle{empty}
\setlength{\parindent}{0pt}


\begin{document}
\begin{tikzpicture}[main]
    \boundingbox
    \usualsetup
    \branch maint -> A;
    \branch master -> E;
    \HEAD -> master;

    \path [>=stealth', draw=black!50, very thick]
        (5,3.75) node {reference to current branch} edge [->] (HEAD label)
        (6.5,2) node {current branch} edge [->] (master)
        (-5,3) node {another branch} edge [->] (maint)
        (-5,-0.5) node {files to go in next commit} edge [->] (index)
        (-5,-2) node {files that you ``see''} edge [->] (work)
        (5,-1) node [text width=6\g, text badly centered]
          {commit objects, identified by SHA-1 hash}
            edge [->] (E)
            edge [->] (D)
            edge [->] (C)

        (-1,2.25) node {child points to parent} edge [->] ($ (B)!.5!(C) $)
        ;

\end{tikzpicture}
\end{document}

Which gives the error:

common.tex|163 warning| LaTeX Warning: Reference `[' on page 1 undefined on input line 163.
common.tex|164 warning| LaTeX Warning: Reference `[' on page 1 undefined on input line 164.
common.tex|165 error| Package pgf Error: No shape named `master' is known.
common.tex|165 error| Package pgf Error: No shape named `master' is known.
common.tex|169 error| Package pgf Error: No shape named `master' is known.
common.tex|169 error| Package pgf Error: No shape named `master' is known.
common.tex|170 error| Package pgf Error: No shape named `maint' is known.
common.tex|170 error| Package pgf Error: No shape named `maint' is known.

It would be great to use your custom code in LaTeX presentations.
Maybe you have a clue ?

Thanks again for your time.

maybe a typo

In section about reset, the ariticle wrote, "If a commit is given with no filenames, the current branch is moved to that commit...", the first commit should be reset, right?

PDF version

Is there some way to get the guide as a PDF file?

Firefox 4

Firefox 3 displays SVG well but Firefox 4 does not. Are there any workarounds? Or, should we switch to direct SVG of HTML5?

Add git subtree to commands

With git subtree you can extract a repository from another one and the other way round.
When you for example have a library from somewhere added to the repository and gradually added changes but then the original library gets some updates, you don't need to circuitously merge the updates manually. You can use git subtree to extract your version with all the related history, then rebase the extracted repository to the original one and after update the library to the extracted one with git subtree.

ambiguity in the arrow for reset in first diagram

In the diagram the command git reset -- files is pointing from the history towards the stage area:

Captura de pantalla de 2019-06-13 13-32-48

however in the description it is stated that:

git reset -- files unstages files; that is, it copies files from the latest commit to the stage. Use this command to "undo" a git add files. You can also git reset to unstage everything.

so there are conflicting statements here:

  • unstages files (implies from stage to WD)
  • copies files from the latest commit to the stage (implies from history to stage)
  • use this command to undo git add (since git add goes from WD to stage, this implies from stage to WD)

The specified usage (git reset -- files) implies an arrow in the same direction as git checkout. Perhaps is worth mentioning the git reset [--hard|--soft] tree-ish variant that actually follows the arrow in the diagram.

It relates to #20

Add some info on git remote control

I would really appreciate if you could add a word on remote control commands, such as pull, fetch, push etc.
You're tutorial is really great, but it is kind of unfinished regarding remote repo sync.
Thank you.

Include `git restore` and `git switch` in your guide

Newer versions of git promote the use of git restore in the help messages in favor of the git checkout command I believe.

git-restore is about restoring files in the working tree from either the index or another commit.

E.g:

> git status
On branch master
Your branch is ahead of 'origin/master' by 124 commits.
  (use "git push" to publish your local commits)

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	modified:   nvim/.config/nvim/lua/usr/plugins/init.lua

Would be nice if you update the guide with this recent change.

directories for the figs

Hello Mark,

One guy told me who to translate the TeX files into Japanese. Since Makefile and common.tex must be modified, I would propose to create directories for the figs. For instance, figs-en and figs-ja. What do you think of this?

Japanese

Hello,
First of all, thank you for the good reference!
I'm Japanese and now trying to translate it into Japanese.
When I finish the translation, can I open it in my web site?

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.