<commit_before>Grip -- GitHub Readme Instant Preview
=====================================

[![Downloads/month on PyPI](http://img.shields.io/pypi/dm/grip.svg)][pypi]
[![Current version on PyPI](http://img.shields.io/pypi/v/grip.svg)][pypi]

Render local readme files before sending off to GitHub.

Grip is a command-line server application written in Python that uses the
[GitHub markdown API][markdown] to render a local readme file. The styles also
come directly from GitHub, so you'll know exactly how it will appear. Changes
you make to the Readme file will be instantly reflected in the browser.


Motivation
----------

Sometimes you just want to see the exact readme
result before committing and pushing to GitHub.

Especially when doing [Readme-driven development][rdd].


Installation
------------

To install grip, simply:

```bash
$ pip install grip
```


Usage
-----

To render the readme of a repository:

```bash
$ cd myrepo
$ grip
 * Running on http://localhost:6419/
```

Now open a browser and visit [http://localhost:6419](http://localhost:6419/).

You can also specify a port:

```bash
$ grip 80
 * Running on http://localhost:80/
```

Or an explicit file:

```bash
$ grip AUTHORS.md
 * Running on http://localhost:6419/
```

Alternatively, you could just run `grip` and visit [localhost:6419/AUTHORS.md][AUTHORS.md]
since grip supports relative URLs.

You can combine the previous examples. Or specify a hostname instead of a port. Or provide both.

```bash
$ grip AUTHORS.md 80
 * Running on http://localhost:80/
```

```bash
$ grip CHANGES.md 0.0.0.0
 * Running on http://0.0.0.0:6419/
```

```bash
$ grip . 0.0.0.0:80
 * Running on http://0.0.0.0:80/
```

You can even bypass the server and **export** to a single HTML file, with all the styles and assets inlined:

```bash
$ grip --export
Exporting to README.html
```

Control the output name with the second argument:

```bash
$ grip README.md --export readme.html
Exporting to readme.html
```

Reading and writing from **stdin** and **stdout** is also supported, allowing you to use Grip with other programs:

```bash
$ cat README.md | grip -
 * Running on http://localhost:6419/
```

```bash
$ grip AUTHORS.md --export - | bcat
```

```bash
$ cat README.md | grip --export - | less
```

This allows you to quickly test how things look by entering Markdown directly in your terminal:

```bash
$ grip -
Hello **world**!
^D
 * Running on http://localhost:6419/
```

*Note: `^D` means `Ctrl+D`, which works on Linux and iOS. On Windows you'll have to use `Ctrl+Z`.*

**Comment / issue-style GFM** is also supported, with an optional repository context for linking to issues:

```bash
$ grip --gfm --context=joeyespo/grip
 * Running on http://localhost:6419/
```

For more details and additional options, see the help:

```bash
$ grip -h
```


Access
------

Grip strives to be as close to GitHub as possible. To accomplish this, grip
uses [GitHub's Markdown API][markdown] so that changes to their rendering
engine are reflected immediately without requiring you to upgrade grip.
However, because of this you may hit the API's hourly rate limit. If this
happens, grip offers a way to access the API using your credentials
to unlock a much higher rate limit.

```bash
$ grip --user <your-username> --pass <your-password>
```

Or use a [personal access token][] with an empty scope (note that a token is
*required* if your GitHub account is set up with two-factor authentication):

```bash
$ grip --pass <token>
```

You can persist these options [in your local configuration](#configuration).
For security purposes, it's highly recommended that you **use an access token
over a password**. (You could also keep your password safe by configuring
Grip to [grab your password from a password manager][keychain-access].)

There's also a [work-in-progress branch][fix-render-offline] to provide
**offline rendering**. Once this resembles GitHub more precisely, it'll
be exposed in the CLI, and will ultimately be used as a seamless fallback
engine for when the API can't be accessed.

Grip always accesses GitHub over HTTPS,
so your README and credentials are protected.


Tips
----

Here's how others from the community are using Grip.

#### Create a local mirror of a Github Wiki

```bash
$ git clone https://github.com/YOUR_USERNAME/YOUR_REPOSITORY.wiki.git
$ cd YOUR_REPOSITORY.wiki
$ grip
```

*By [<NAME>](https://twitter.com/gourneau/status/636329126643658753)*.

*Want to share your own? [Say hello][twitter] or [see below](#contributing).*


Known issues
------------

- [ ] GitHub introduced read-only task lists to all Markdown documents in
      repositories and wikis [back in April][task-lists], but
      [the API][markdown] doesn't respect this yet.
<commit_msg>Readme: Add the word 'checkbox' to the task list known issue for searchability.<commit_after>Grip -- GitHub Readme Instant Preview
=====================================

[![Downloads/month on PyPI](http://img.shields.io/pypi/dm/grip.svg)][pypi]
[![Current version on PyPI](http://img.shields.io/pypi/v/grip.svg)][pypi]

Render local readme files before sending off to GitHub.

Grip is a command-line server application written in Python that uses the
[GitHub markdown API][markdown] to render a local readme file. The styles also
come directly from GitHub, so you'll know exactly how it will appear. Changes
you make to the Readme file will be instantly reflected in the browser.


Motivation
----------

Sometimes you just want to see the exact readme
result before committing and pushing to GitHub.

Especially when doing [Readme-driven development][rdd].


Installation
------------

To install grip, simply:

```bash
$ pip install grip
```


Usage
-----

To render the readme of a repository:

```bash
$ cd myrepo
$ grip
 * Running on http://localhost:6419/
```

Now open a browser and visit [http://localhost:6419](http://localhost:6419/).

You can also specify a port:

```bash
$ grip 80
 * Running on http://localhost:80/
```

Or an explicit file:

```bash
$ grip AUTHORS.md
 * Running on http://localhost:6419/
```

Alternatively, you could just run `grip` and visit [localhost:6419/AUTHORS.md][AUTHORS.md]
since grip supports relative URLs.

You can combine the previous examples. Or specify a hostname instead of a port. Or provide both.

```bash
$ grip AUTHORS.md 80
 * Running on http://localhost:80/
```

```bash
$ grip CHANGES.md 0.0.0.0
 * Running on http://0.0.0.0:6419/
```

```bash
$ grip . 0.0.0.0:80
 * Running on http://0.0.0.0:80/
```

You can even bypass the server and **export** to a single HTML file, with all the styles and assets inlined:

```bash
$ grip --export
Exporting to README.html
```

Control the output name with the second argument:

```bash
$ grip README.md --export readme.html
Exporting to readme.html
```

Reading and writing from **stdin** and **stdout** is also supported, allowing you to use Grip with other programs:

```bash
$ cat README.md | grip -
 * Running on http://localhost:6419/
```

```bash
$ grip AUTHORS.md --export - | bcat
```

```bash
$ cat README.md | grip --export - | less
```

This allows you to quickly test how things look by entering Markdown directly in your terminal:

```bash
$ grip -
Hello **world**!
^D
 * Running on http://localhost:6419/
```

*Note: `^D` means `Ctrl+D`, which works on Linux and iOS. On Windows you'll have to use `Ctrl+Z`.*

**Comment / issue-style GFM** is also supported, with an optional repository context for linking to issues:

```bash
$ grip --gfm --context=joeyespo/grip
 * Running on http://localhost:6419/
```

For more details and additional options, see the help:

```bash
$ grip -h
```


Access
------

Grip strives to be as close to GitHub as possible. To accomplish this, grip
uses [GitHub's Markdown API][markdown] so that changes to their rendering
engine are reflected immediately without requiring you to upgrade grip.
However, because of this you may hit the API's hourly rate limit. If this
happens, grip offers a way to access the API using your credentials
to unlock a much higher rate limit.

```bash
$ grip --user <your-username> --pass <your-password>
```

Or use a [personal access token][] with an empty scope (note that a token is
*required* if your GitHub account is set up with two-factor authentication):

```bash
$ grip --pass <token>
```

You can persist these options [in your local configuration](#configuration).
For security purposes, it's highly recommended that you **use an access token
over a password**. (You could also keep your password safe by configuring
Grip to [grab your password from a password manager][keychain-access].)

There's also a [work-in-progress branch][fix-render-offline] to provide
**offline rendering**. Once this resembles GitHub more precisely, it'll
be exposed in the CLI, and will ultimately be used as a seamless fallback
engine for when the API can't be accessed.

Grip always accesses GitHub over HTTPS,
so your README and credentials are protected.


Tips
----

Here's how others from the community are using Grip.

#### Create a local mirror of a Github Wiki

```bash
$ git clone https://github.com/YOUR_USERNAME/YOUR_REPOSITORY.wiki.git
$ cd YOUR_REPOSITORY.wiki
$ grip
```

*By [<NAME>](https://twitter.com/gourneau/status/636329126643658753)*.

*Want to share your own? [Say hello][twitter] or [see below](#contributing).*


Known issues
------------

- [ ] GitHub introduced read-only task lists (checkboxes) to all Markdown
      documents in repositories and wikis [back in April][task-lists], but
      [the API][markdown] doesn't respect this yet.

{'fraction_non_alphanumeric': 0.12579667746317, 'fraction_numerical': 0.01713509560129558, 'mean_word_length': 3.92133676092545, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 8, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1131687', 'n_tokens_mistral': 3112, 'n_tokens_neox': 2786, 'n_words': 1231}