Docs

Overview

GitQuiz lets you create and host interactive quizzes for your git repos.

Quizzes are a fun and engaging way to onboard new developers to your codebase and keep them up-to-date as your application evolves.

Any repo collaborator can take quizzes and contribute new questions. Each repo has one quiz and each quiz has multiple questions. You can create groups to keep related questions together.

.gitquiz

Quiz data is stored in a special folder in the root directory of your repo called .gitquiz. It should be not be gitignored.

This folder contains the following files:

  • quiz.json
    A JSON representation of your quiz, generated by the GitQuiz CLI.
  • key.pem
    The public key provided by GitQuiz for your repo, used by the CLI to encrypt answers.
  • readme.md (optional)
    A markdown file whose contents will appears on your repo's page on gitquiz.com if it exists. Good for introducing developers to your application.

Getting Started

Publishing a quiz takes under a minute.

First, signup to create an account. GitQuiz is completely free for unlimited public repos and up to one private repo.

Activate a repo by clicking the "Add" button:

memos.dev

You should see a public key on your repo's page at gitquiz.com/gh/[repo_owner]/[repo_name]

memos.dev

In that repo, install the CLI.

memos.dev
$ npm install --save-dev gitquiz

Initialize GitQuiz with the public key found on your repo's page.

memos.dev
$ npx gitquiz init

Use the interactive prompt to add your first question, commit and push.

memos.dev
$ npx gitquiz add
$ git add .
$ git push origin master

Refresh your repo's page at gitquiz.com/gh/[repo_owner]/[repo_name] and you should see a "Get Started" button. Click it to start the quiz.

memos.dev

Updating your quiz

It's easy to add, remove or edit questions in your quiz.

Using the CLI (recommended):

Add a question:

memos.dev
$ npx gitquiz add

Edit a question or answer:

memos.dev
$ npx gitquiz edit [id]

Remove a question:

memos.dev
$ npx gitquiz rm [id]

Manually:

Use the id and encrypt commands to generate a question ID and encrypted answer. Modify the JSON to add a new question object to the questions array, containing an ID, question and encrypted answer.

memos.dev
$ npx gitquiz id
$ npx gitquiz encrypt

Edit a question by simply replacing the question text in the JSON. To modify an answer, use the encrypt command and replace the current answer value.

memos.dev
$ npx gitquiz encrypt

To remove a question simply remove the question object from the questions array.

Groups

Groups are useful to visually organize related questions together.

Create a new group:

memos.dev
$ npx gitquiz groups add [group name]

Move question objects into the group's questions array.

Validation

Validate and preview your quiz before publishing.

Use these commands to validate your JSON and preview the quiz structure:

memos.dev
$ npx gitquiz validate
$ npx gitquiz preview

Notifications

Email notifications keep your collaborators up to date on your codebase and inform them of new questions.

By default you will receive an email notification whenever a new question is added to a repo you collaborate on, or an existing answer is changed. This helps you stay up-to-date on any changes.

You can disable these notifications in your account settings.

Status badge

Display your quiz's completion rate.

Your badge will be accessible at the following URL: gitquiz.com/gh/[repo_owner]/[repo_name]/badge. You can find pre-generated markdown on the repo settings page.

Support

We are here to answer any questions you may have.

Email support at answers@gitquiz.com

FAQ

Answers to some frequently asked questions.

How many questions can a quiz have?

There is currently no limit to the number of questions or groups in a quiz.

What happens when I delete a question?

We keep all previous question responses, so if you ever add the question back with the same ID, your team's responses will still be there.

What if I don't want to use NPM?

Support for other ecosystems is coming soon. In the meantime, you can use any unique ID for your questions, and use any tool to encrypt the answers with your public key.

Which branch is used for the quiz?

The quiz JSON on master branch will be used to generate the quiz. In the future we'll add support for other branches.

Will I lose my response history if I deactivate a repo?

We will keep your response history, which is linked to the question IDs. When you reactivate the repo everything will be just as you left it.

I have a feature request or want to report a bug.

Please file an issue in our support repo.

I have a question that wasn't answered here.

Email support at answers@gitquiz.com.