imag/README.md

150 lines
4.7 KiB
Markdown
Raw Normal View History

2017-04-28 09:34:41 +00:00
# imag - [imag-pim.org](https://imag-pim.org)
2015-10-30 22:52:43 +00:00
2016-10-03 18:44:06 +00:00
`imag` is a commandline personal information management suite.
2016-10-27 09:12:20 +00:00
**This application is in early development. There are _some_ things that work,
but we do not consider anything stable or usable at this moment. Feel free to
play around anyways.**
2018-04-18 13:03:05 +00:00
## Vacation notice
**Notice:** I, the author of imag, will be on vacation from mid-May 2018 until
early 2019. I hope I can continue develop imag during that time, but I cannot
guarantee that. I hope I can continue development of imag after that and I
certainly plan to do so.
But from May 2018 until February 2019, expect long response times.
2018-04-18 13:03:05 +00:00
2016-10-27 09:12:46 +00:00
## Goal / What is imag?
2016-10-03 18:44:06 +00:00
Our (long-term) goal is to
2016-10-03 18:44:06 +00:00
> Create a fast, reliable commandline personal
> information management suite which covers all aspects of personal information
> management, consists of reusable parts and integrates well with known
> commandline tools.
2017-09-23 19:26:03 +00:00
Yes, imag is a rather ambitious project as it tries to reimplement functionality
2017-08-25 15:43:12 +00:00
for several "personal information management aspects". It is a hobby project,
2018-01-19 20:52:47 +00:00
keep that in mind. We try to use standards like vcard, icalendar and others
wherever possible.
2016-10-27 09:12:46 +00:00
2018-01-19 20:52:47 +00:00
Have a look at [the documentation](./doc/) for some more words on this.
2017-08-25 15:43:12 +00:00
## Building/Running
2016-10-27 11:03:02 +00:00
Here is how to try `imag` out.
2016-10-03 18:44:06 +00:00
2017-04-22 09:45:08 +00:00
`imag` is a _suite/collection_ of tools (like git, for example) and you can
build them individually.
All subdirectories prefixed with "`libimag"` are libraries.
2016-10-03 18:44:06 +00:00
All subdirectories prefixed with `"imag-"` are binaries and compiling them will
give you a commandline application.
2016-07-30 10:33:55 +00:00
### Building
We use `cargo` for building all crates in this repository.
Make sure to use a recent `cargo`, at least one with workspace support.
Building all crates works with `cargo build --all`, building individual crates
by specifying the `--manifest-path` flag to cargo.
2018-01-19 20:52:47 +00:00
### Running
2016-10-27 09:19:33 +00:00
After you build the module you want to play with, you can simply call the binary
itself with the `--help` flag, to get some help what the module is capable of.
If you installed the module, you can either call `imag-<modulename>` (if the
install-directory is in your `$PATH`), or install the `imag` binary to call
`imag <modulename>` (also if everything is in your `$PATH`).
Call `imag --help` to see which modules are found and can be used.
Call `imag --versions` to print the versions of all modules.
2018-01-19 20:52:47 +00:00
2018-04-27 09:29:49 +00:00
## Example usage
As imag is a big and complex project, we cannot show all tools of the suite
here. But to give you some idea, here's an example:
```bash
# Lets initialize imag
imag init
# Recursively import vcf files
imag contact import /home/user/contacts
# Create a contact (vcf) in the private collection
imag contact create --file /home/user/contacts/private
# Add a diary entry
imag diary -p private create
# Uh, I forgot something in a diary entry, select one (or multiple) and edit it
2018-04-27 09:29:49 +00:00
# use the `fzf` tool here (not a part of imag) to select from the IDs
imag diary -p private list | fzf -m | imag edit
2018-04-27 09:29:49 +00:00
# Link a contact to the diary entry
imag link diary/private/2018/01/01/00:00:00 contact/bc222298-casf-40a4-bda1-50aa980a68c9
# Annotate a contact with some notes
imag annotate add contact/bc222298-casf-40a4-bda1-50aa980a68c9 contact-notes
# Write down some notes named "pineapple"
imag notes create "pineapple"
# Where was that contact again?
imag grep Eva # also possible with `imag contact find Eva`
2018-04-27 09:29:49 +00:00
# Okay, we need to add some imag-internal notes to that contact
imag grep Eva -l | imag edit
2018-04-27 09:29:49 +00:00
# Now save our work
imag git add . # "imag-git" simply calls git in the imag store
imag git commit -m 'Commit message'
```
2016-10-07 15:16:45 +00:00
## Staying up-to-date
2017-04-28 09:34:41 +00:00
We have a [official website for imag](https://imag-pim.org), where I post
[release notes](https://imag-pim.org/releases/) and monthly(ish) updates what's
2017-09-11 14:42:06 +00:00
happening in the source tree ([RSS here](https://imag-pim.org/index.xml)).
2017-04-28 09:34:41 +00:00
We also have a [mailinglist](https://imag-pim.org/mailinglist/) where I post
2016-10-27 09:19:44 +00:00
updates and where discussion and questions are encouraged.
2018-01-19 20:52:47 +00:00
## Documentation
2016-10-27 09:21:22 +00:00
2018-01-19 20:52:47 +00:00
We have some documentation in [the ./doc subtree](./doc/)
which can be compiled to PDF or a website using pandoc.
2018-01-19 20:52:47 +00:00
It might not be up to date, though.
Developer documentation for the last release is available
[on docs.rs](https://docs.rs/releases/search?query=imag).
2015-10-30 22:52:43 +00:00
2016-10-03 18:44:06 +00:00
## Please contribute!
2016-10-04 11:49:57 +00:00
We are looking for contributors!
Feel free to open issues (by writing to
[the mailinglist](https://imag-pim.org/mailinglist/))
for asking questions, suggesting features or other things!
2016-10-03 18:44:06 +00:00
Also have a look at [the CONTRIBUTING.md file](./CONTRIBUTING.md)!
2018-01-19 20:52:47 +00:00
## Contact
2016-08-02 12:22:58 +00:00
Feel free to join our new IRC channel at freenode: #imag
2017-04-28 09:34:41 +00:00
or our [mailinglist](https://imag-pim.org/mailinglist/).
2018-01-19 20:52:47 +00:00
## License
2015-11-30 15:30:20 +00:00
We chose to distribute this software under terms of GNU LGPLv2.1.
2015-11-08 16:35:11 +00:00
2018-01-19 20:52:47 +00:00