Git Product home page Git Product logo

learngitbranching's Introduction

LearnGitBranching

PRs Welcome

LearnGitBranching is a git repository visualizer, sandbox, and a series of educational tutorials and challenges. Its primary purpose is to help developers understand git through the power of visualization (something that's absent when working on the command line). This is achieved through a game with different levels to get acquainted with the different git commands.

You can input a variety of commands into LearnGitBranching (LGB) -- as commands are processed, the nearby commit tree will dynamically update to reflect the effects of each command:

demo-gif

This visualization combined with tutorials and "levels" can help both beginners and intermediate developers polish their version control skills. A quick demo is available here: https://pcottle.github.io/learnGitBranching/?demo

Or, you can launch the application normally here: https://pcottle.github.io/learnGitBranching/

Sandbox Mode

By default the application launches in "sandbox mode" with a basic repository already created. Here you can enter commands and mess around with a repository as much as you like. Keep in mind you can

  • undo to undo the effects of the last command
  • reset to start over with a clean slate (works in levels too)
  • git clone to simulate remote repositories!

Sandbox mode can be great for demonstrating something to a friend, but the real learning is with levels...

Levels

Type levels to see the available lessons / challenges (and which ones you have solved so far). Each level series aims to teach some high-level git concept, and each tab of levels separates major worlds of info (like remote repositories versus local).

For some added fun, there is a "git golf" concept where we keep track of how many commands you use to solve each level. See if you can match all of our records!

Sharing permalinks

You can share a link to LearnGitBranching with an arbitrary set of commands that will execute upon load by using the command URL parameter. You will also likely want to disable the intro dialog for this case with the NODEMO url param; here is an example to get started.

Level Builder

You can build levels with the build level command. A dialog will walk you through the process, and at the end it will show you a JSON blob that represents the level you just created. Paste that in a gist or directly into an issue and I can check it out / merge in your changes! You can also share this level directly with friends by having them run import level and paste the JSON in the resulting text field, or simply send them a custom URL with the the gist ID in the parameters, like so: https://pcottle.github.io/learnGitBranching/?gist_level_id=a84407351f9c9f0cb241

Reporting Bugs / Opening Issues

When reporting bugs, try running the command debug_copyTree() in your JS console when in a state just before reproducing a bug. This can avoid having to copy all the commands you used to get into a specific state. (I can then use the importTreeNow command to get to that exact state)

Building yourself / Contributing Functionality

For contributing core functionality in the app, you'll probably want to test your changes at least once before submitting a pull request. That means you'll need the "gulp.js" build tool to build the app:

https://gulpjs.com/docs/en/getting-started/quick-start

You'll also need yarn to download all the dependencies of the project.

The general workflow / steps are below:

git clone <your fork of the repo>
cd learnGitBranching
yarn install

git checkout -b newAwesomeFeature
vim ./src/js/git/index.js # some changes
yarn gulp fastBuild # skips tests and linting, faster build

# after building you can open up your browser to the index.html
open ./index.html
# file generated and see your changes

vim ./src/js/git/index.js # more changes
yarn gulp build # runs tests and lint

git commit -am "My new sweet feature!"
git push
# go online and request a pull

Alternatively, you can also build and run the app in a pre-configured online workspace:

Open in Gitpod

Other Technical Details

LearnGitBranching is a pretty simple application (from a technical perspective). There's no backend database or any AJAX requests -- it's a 100% clientside application written in JavaScript. The production version (on github.io) literally just serves up an HTML page with some JS and CSS.

Here is the high-level process of the build:

  • CSS is written into just one stylesheet (there is not a whole ton of styling)
  • New HTML is written into a template HTML file (template.index.html). This is only needed for new views
  • The app is "built", which outputs:
    • index.html in the root directory
    • CSS and JS files in ./build directory
  • If the app is being built for production, then these CSS and JS files are hashed (to bust caches) and tests are run
  • That's it!

Thus, if you build the app locally, all you have to do in order to run the app is just open up index.html in the root directory of the repo. Pretty simple

Docker

You can run the most recently built stable image with docker run -p 8080:80 ghcr.io/pcottle/learngitbranching:main. Access your environment with at http://localhost:8080/

You can build the app and image with the command: docker build -t ghcr.io/pcottle/learngitbranching:latest. See the Makefile for information on how to build locally with docker.

Some of our amazing contributors

Helpful Folks

A big shoutout to these brave souls for extensively testing our sandbox and finding bugs and/or inconsistencies:

  • Nikita Kouevda
  • Maksim Ioffe
  • Dan Miller

And the following heroes for assisting in translating:

  • Jake Chen
  • 우리깃 ("urigit")
  • "bcho"
  • "scientific-coder"
  • "ace-coder"
  • Joël Thieffry
  • Jens Bremmekamp ("nem75")
  • "hilojack"
  • Ming-Hsuan-Tu ("twmht")
  • Mikhail Usov ("mikhailusov")
  • Matias Garcia Isaia ("mgarciaisaia")
  • Marc-Olivier Arsenault ("marcolivierarsenault")
  • Eroany H Leader ("lhyqy5")
  • Honorat ("ahonorat")
  • Vasil Kulakov ("coyl") & Lyubov Agadjanyan ("shayenblue")
  • Aliaksei Berkau ("alexeiberkov")
  • Mizunashi Mana ("mizunashi-mana")
  • YourSenseiCreeper
  • Olsza

Also huge shoutout for everyone who has put up a pull request that was pulled! Check out the 30+ contributors we have in the Contributors View

And everyone who has reported an issue that was successfully closed!

learngitbranching's People

Contributors

0xk3rn3lp4n1c avatar ahonorat avatar alexandear avatar alexeiberkov avatar aschrab avatar bcbcarl avatar birdalicious avatar casillas-m avatar coyl avatar dependabot[bot] avatar donkirkby avatar eatdrinksleepcode avatar flyingbot91 avatar hong4rc avatar juhokang avatar krzysiekwie avatar lroellin avatar maxoliverbr avatar nlehuby avatar olsza avatar panaeon avatar pcottle avatar shardanasoft avatar spatrol avatar sunshowers avatar twmht avatar ulyssear avatar vinothmdev avatar waldyrious avatar yoursenseicreeper 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  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

learngitbranching's Issues

Git does not store deltas.

Git stores snapshots, not deltas. If a file has changed twice, there will be two copies of it in the repository.

However, Git does re-use files that haven't changed between commits, keeping repositories small.

With this in mind, your intro is lying to people.

failure to represent genuine use

I've worked through the tutorials a little, as far as the rebase one. I'm entirely new to git having only used it previously to download an entire codebase (or two) and most recently - 2 weeks ago - started using it via a Netbeans plugin.

The problem I'm having is understanding what the processes are doing to the code that one is trying to version - the tutorial appears to miss out the fact that one is operating on a codebase and the point is to provide versioning on that codebase (I assume).

For example in the first lesson one performs 2 commits, OK. But what happens when one does that and why would one perform a commit. Presumably the reason to commit is to record a new "checkpoint" for the code that one can go back to or share? So there's a step of changing the code between the 2 commits isn't there? IMO you need some way to show that there is an intermediate step of writing code.

Then when branching I guess that you get multiple versions of a file and these get merged somehow to produce a master version in the master branch, but none of this detail of the files is shown.

Apologies if this is all wrong thinking, like I say I'm a newb on git but this is the part of the tutorials that seems most lacking to me. They definitely have some value for me but as I'm mainly trying to understand git WRT code versions it is lacking, as I've said.

Thanks.

User misspeling commands contributes to total

When either a branch name or a command is misspelt, it contributes towards the total. This is quite annoying because the message about whittling down the number of commands still shows up despite the number of valid commands entered being on par with the solution.

Internationalization

Kudos for the great app !

I'd like to translate it to French. Could you tell me how you'd like me to do it ? (markdowns could be a map of intl_id → vectors with current vector strings for "en_US", but what about the rest of the app ?)

Cheers,

B.

Not working in Opera (12.14.1738/x64)

I was just pointed to this awesome project by a friend. Sadly, it does not work in Opera (12.14.1738/x64).

More specifically, it does not come up with the introductory windows that one gets in other browsers. No clues as to the cause - it just seems to hang on the "help" command.
It was subsequently a bit annoying to discover that Firefox doesn't work either, nor does IE.

Thank you for the anticipated resolution.

'define name' breaks the builder

Windows 7, Chrome 24.0.1312.57 m

To reproduce:

  • build level
  • define name

This just hangs without displaying a dialog -- the green up/down arrow is displayed beside the command. Further commands do nothing. "Uncaught Error: woah we dont support that method yet" is display in console after typing define name.

Trace:

Uncaught Error: woah we dont support that method yet bundle.min.16cb085d.js:1
v.extend.processLevelBuilderCommand bundle.min.16cb085d.js:1
a.trigger bundle.min.16cb085d.js:1
f.Model.extend.processCommand bundle.min.16cb085d.js:1
f.Model.extend.popAndProcess bundle.min.16cb085d.js:1
f.Model.extend.sipFromBuffer bundle.min.16cb085d.js:1
(anonymous function) bundle.min.16cb085d.js:1

Command with incorrect params is counted for final number of steps

intro5
type the following:
git reset HEAD~1
git checkout pushed
git revert (fails with error)
git revert HEAD

But in the "end screen" you'll get the message that you used 4 commands "You solved the level in 4 command(s); our solution uses 3."

What is interesting that if you use incorrect command name like "git checkout11 pushed" it fails with error but isn't counted.

grunt build failing

Hi, awesome project! I'd like to add some more shortcuts but I can't seem to build the project. I ran npm install and then npm install grunt -g but I'm getting this error when trying to build:

[lkysow@Lukes-Macbook learnGitBranching (master)]$ grunt build
Loading "shell.js" tasks and helpers...ERROR
>> TypeError: Cannot read property '_' of undefined
<WARN> Task "shell" not found. Use --force to continue. </WARN>

Aborted due to warnings.

And when run with --force:

lkysow@Lukes-Macbook learnGitBranching (master)]$ grunt  build --force
Loading "shell.js" tasks and helpers...ERROR
>> TypeError: Cannot read property '_' of undefined
<WARN> Task "shell" not found. Used --force, continuing. </WARN>

Done, but with warnings.

If you think the issue I'm seeing is something peculiar to my environment then no worries, I'll continue trying to debug it myself.

i18n support

Is possible to translate learnGitBranching into other language? Because some beginner may not good at English.

Thanks for your great job!

Doesn't work in IE

The windows buttons are positioned vertically (did you forget to add float:left and set their width properly?)

The first console window rarely loads its contents.

I also see this in the console:
SCRIPT438: Object doesn't support property or method 'getEvents'
bundle.min.16cb085d.js, line 1 character 249445

P.S. Debugging half-meg of minified JS is totally cool.

Helper command bar

There should be a command bar at the bottom that includes basic helper commands -- undo, help, reset, and maybe the demo!

show command not recognized

Executing just 'show' gives the error:
The command "show" isn't supported, sorry!

I was expecting help to see the available show commands (like 'show solution'). To take this even further, an overview of the available commands would be useful (help doesn't help here ;) ). Nice catch on 'ls' btw!

Level 2 branching does not complete if errors are made

If you make an error or typo on level-2 branching and still complete the proper steps the goal does not complete, you must start over from scratch by re-refreshing the browser.

Reproduce.

git branch bugfix git branch bugFix git checkout bugFix

git checkout <ref> -b <name>

This correctly branches from C0:
git checkout -b test C0

This always branches from HEAD:
git checkout C0 -b test

Firefox 19.0 - CSS Problem

There is a big problem with the CSS in Firefox 19.0 (Mac)

As you can see in the screenshot everything is mixed up.
Screen Shot 2013-02-22 at 12 16 28

I am not that good of an CSS Developer, otherwise I would help.

Typos in level dialogs

I noticed a couple of typos as I was going through the levels. I'll post a pull request with the details.
Thanks for the cool tutorial.

Problem with cherry-pick level mixed1

Hello, I have a problem with using cherry-pick (ignore if my solution is wrong), but when I do cherry-pick in this level, it "freezes", not sure if it's a problem with chrome tho.

Google Chrome: Version 25.0.1364.97 m

As you can see from the image, the second command does not run due to the cherry-pick being stuck

Learn Git Branching

Console:

Should be empty:
Array[1]
0: TypeError
message: "Cannot call method 'highlightTo' of undefined"
stack: "TypeError: Cannot call method 'highlightTo' of undefined↵From previous event:↵"
proto: Error
length: 1
proto: Array[0]
bundle.min.eac15d86.js:1
Uncaught TypeError: Cannot call method 'highlightTo' of undefined bundle.min.eac15d86.js:1

Bug in level rebasing1

Just typing

git reset another

in the master branch wil instantly 'solve' the problem, without getting the same tree as the target.

This doesn't seem to be a valid solution.

Typo in level intro 5

Part of the help text for the level intro 5 is "With resetting, you can push out your changes to share with others."

Shouldn't that be "With reverting, you can push out your changes to share with others."?

Moving Around in Git -- Level Request (relative refs)

In the level where you introduce reset and revert there really isn't any explanation for why we type HEAD or HEAD~1. This doesn't really help a user learn what those mean and why that is the command one needs to use.

Simpler solution to Juggling Commits 2 not recognized

This 3-command sequence achieves the desired outcome

git rebase newImage master # checkout and fast-forward master
git commit --amend
git cherry-pick caption

This 4-command sequence also achieves the same thing

git checkout master
git reset --hard newImage
git commit --amend
git cherry-pick caption

Neither of the above are recognized. The expected solution seems to be

git checkout master
git cherry-pick newImage # identical except for the date
git commit --amend
git cherry-pick caption

although this also works

git rebase newImage master
git commit --amend
git commit --amend  # yes, twice
git cherry-pick caption

Extra space in entered command

I tried to delete my branch bugfix

$git branch -D bugfix

but after pressing enter, I got following message at terminal ( extra space between bugfix with error message)

$git branch -D bug fix unknown ref bug

git-flow

This is a very nice tutorial. Any plans for doing one for git-flow?

Modal windows cannot be dismissed on smaller screens

When using the site on smaller screen resolutions (in this case 1366x768) modal windows (such as the first Alert dialog - pictured below) cannot be dismissed as the button at the bottom of the dialog is not visible, and browser scroll bars do not work (in this case for Google Chrome 24.0.1312.57), and the red Mac OS X style button in the top left of the dialog does not work either.

The ability to either dimiss the modal window using the red button, or use the browser scroll bars should be enabled when such a window appears.

CapturFiles_24

Rebase level 2's solution uses commands not previously discussed

The level "Branch Spaghetti" has a solution that uses interactive rebase, a mode not discussed in the lessons up to that point. A newcomer to git will be absolutely unable to solve that level. (And even experienced git users will be unable to solve it... interactive rebase is just not used very often.)

Typo in intro5

"That's because this new commit C1' introduces changes -- it just happens to introduce changes that exactly reverses the commit of C1."

Should be C2' and C2.

intro5 state problems when moving back & forth in hint

First off, nice project! Very fun to play around with.

I was able to create some minor problems in Chrome with the introduction to intro5. Others levels may be susceptible to the same issue. The issue is going back and forward, causing the the graphs to no longer line up with the descriptions:

1.) Click "git reset head~1"
2.) Click next
3.) Click back

both the reset and revert panels are all missing a commit, and no longer line up with the commits mentioned in the text.

Add an undo button

Sometimes you want to try different stuff and simply undo the last command and try another one, it would be great if there was at least an undo button, and preferably an undo stack!

Restart level with new command-count/undo does not reset command count

I just discovered the "undo" command, but it does not reset the command-count but restarts the level.

There should be a way to restart a level (without showing the level-hint) from the commandline and resetting the counter.

EDIT: Ooops seems to be my mistake. Now it did.
But the desire for a "full reset/undo" is still there.

intro6.

Page with "git revert HEAD".
After click the "git revert HEAD" button on the image we are look C2'( C1' needed )

'edit dialog' cannot test individual dialogs nor the entire view

Windows 7 - Chrome Windows 7, Chrome 24.0.1312.57 m

To reproduce:

  • build level
  • edit dialog
  • Add a ModalAlert with anything, click confirm.
  • Click 'Test' on the newly created view. Nothing happens, error in console
  • Click 'Test Entire View'. Nothing happens, error in console

Both 'Test' buttons yield "Uncaught TypeError: undefined is not a function" in error console

Show a command documentation alongside the console text

It would be great to have a "documentation" feature that would give a brief overview of the results of each command (eg. a popup window with trees that shows what git rebase master bug_fix would do) or git help rebase could show a little window with the illustration.

Scroll bar in command window doesn't work in Chromium

I'm currently running Version 26.0.1404.0 (180391) of Chromium. In the command window, after you have entered enough commands a scroll bar will appear. I am unable to interact with the scroll bar and the mouse scroll wheel doesn't scroll the window either.

image

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.