Very much a WIP project
squirrel is a command line program that tracks you writing progress. The program can tell you:
- How many days are left before due-date.
- How many words you've written each day.
- ...
Squirrel's design was inspired by git
's design (from a user perspective at least). To start a project, you have to initialize a new project in your directory of choice, which will create a .squirrel
folder structure in your directory similar to .git
directories.
That folder will store:
- project metadata (e.g name, description, goal, due date, etc.).
- word counts.
However squirrel
is not a static program otherwise we couldn't track progress without explicit input of the user.
The watch
command will listen to any changes and update the count.
Many people use different file formats and software to write.
The behaviour of squirrel
can be changed with plugins to fit particular needs.
The project-type
field set by the users determines which plugin will be used.
Plugins available now:
- text
- texcount
hmm, haven't found your project type? you can write Python code? Please make a pull request :)
Tested Python versions:
- python 3.8
- python 3.9
- python 3.10
Python versions:
All pip dependencies are in the Pipfile
file.
You can install squirrel
with pip
pip install squirrel-writer
Grab the repo, install dependencies, and voila.
git clone https://github.com/squirrel-writer/squirrel
cd squirrel
pipenv install --dev && pipenv shell
# Install the package in editable mode
# use pip with this command, so that Pipfile doesn't get modified
pip install -e .
# To run unittests
pytest
# Or use tox to run tests on multiple versions
tox
There 4 main verbs to interact with squirrel:
- init
- watch
- set
- overview
You can learn more about their options with -h
or --help
option. (e.g squirrel init -h
, etc.)
squirrel init -n Assay --project-type text
Set can be used after init to change or set fields.
squirrel set --name "English Assay" --goal 10000 --due 05/01/2022
Run this command to tell squirrel to watch your writing.
squirrel watch start --daemon
squirrel watch status
squirrel watch stop
overview
displays your writing progress.
# A general overview
squirrel overview
# to get a barchart
squirrel overview --graph
Similar to .gitignore
files in git repos, you can ignore files in squirrel
projects
by adding a .squirrelignore
file in the root of your project.
Note that .*
, *~
, *~
and .<dir>
are ignored by default
Example file structure:
- .squirrel/
- thesis.tex
- .squirrelignore
# .squirrelignore file
# How to ignore files and file types
*.tmp
README.md
# How to ignore directories
tmp_dir/
If you're looking to help squirrel
become better, we're always looking
for people to test, report any bugs, improve documentation,
and submit any fixes or features.
Any contribution (even documentation) goes a long way.
PRs are welcome :). Make sure to open an issue before submitting the PR so that everybody can chip in with their opinion.
If your PR with be changing some dependencies, don't forget to update Pipfile.lock
as well as the dependencies in setup.py
with pipenv-setup
.
All plugins are located in squirrel/plugins
. Each plugin has its own directory, which has in it the Python module (e.g example_plugin.py
) and the yaml
config file.
The yaml
file stores:
- metadata of the plugin
- any dependencies the plugin needs to work properly.
An example plugin can be found in squirrel/plugins/example_plugin/
.
Every plugin you create must have a get_count(files) -> int
function in their module that counts all the files and returns an int.
For squirrel to find your plugin and be able to load it, the plugin must respect a structure.
Plugin Structure:
There are 2 main files that make plugins work correctly. A .py
file/module that contains the get_count
function and a .yaml
config file.
The folder that contains the plugin, the plugin itself (e.g python module), and the config file should have the same name.
For example, if you are creating a plugin called markdowncount
, this is how it should be structured:
- plugins/
- markdowncount/
- markdowncount.py
- markdowncount.yaml
And the files might look like this:
# markdowncount.py
def get_count(files) -> int:
return ...
name: markdowncount
description: ....
version: 0.0.1
Look at this example for more detail.
Third-party requirements:
If a plugin needs some thrid-party dependencies (system
or pip
), they must be declared in the yaml
config file of the plugin.
pip
or system
dependencies can be declared this way inside the config file:
deps:
sys:
- texcount
pip:
- panda
The testing suite is very small at the moment (about 7 tests). We need help in making it robust and exhaustive. Any contribution on this regard is highly appreciated.
squirrel
is still in an experimental stage. Bugs are probably present, so any testing and bug reporting is welcome.
Squirrel art
created by Joan G. Stark who is known in the ASCII world with the initials jgs
.
_
.-'` `}
_./) / }
.'o \ | }
'.___.'`.\ {`
/`\_/ , `. }
\=' .-' _`\ {
`'`;/ `, }
_\ ; }
jgs /__`;-...'--'