Spend time with the people you care about. Introvert-tested. Extrovert-approved.
NOTE: Participation is encouraged! Make Issues, ask questions, submit Pull Requests (even if it's your first time contributing to open-source—you'll get lots of help), and give feedback!
- Overview
- Installation
- Usage
- Core concepts
- Global flags
- Syncing across multiple machines
- Command reference
- Other documentation
- Contributing (it's encouraged!)
- Code of Conduct
- License
friends
is both a Ruby library and a command-line interface that
allows you to keep track of your relationships with the people you
care about.
friends
gives you:
- More organization around staying in touch with friends and family.
- A way to track the ebbs and flows of your relationships over time.
- Suggestions for who to call or hang out with when you have free time, whether it's fifteen minutes or an entire weekend.
- A low-cost way to record and remember big moments in your life.
Its philosophy emphasizes:
- Simplicity—it should be quick and easy to use.
- Transparency—all data is stored in a human-readable Markdown file. No
proprietary formats here! And in addition to being open-source,
friends
is very much open to new ideas. Contribute! - Intelligence—specify dates with English phrases like "yesterday." Specify
friends with their first names, even when you're friends with many Joannes.
friends
will figure it out.
$ gem install friends
Easy, huh?
friends
is structured around several different types of things:
- Activities: The things you do. Each activity has a date associated with it. Activities may optionally contain any number of friends, locations, and tags.
- Friends: The people you do activities with. Each friend has a name and,
optionally, one or several nicknames. (Examples:
John
,Grace Hopper
) - Locations: The places in which activities happen. (Examples:
Paris
,Marie's Diner
) - Tags: A way to categorize your activities with tags of your
choosing. (Examples:
@exercise
,@school
)
The friends.md
Markdown file that stores all of your data contains:
- an alphabetical list of all locations:
### Locations:
- Atlantis
- Marie's Diner
- Paris
- an alphabetical list of all friends and their nicknames and locations:
### Friends:
- George Washington Carver
- Grace Hopper (a.k.a. The Admiral a.k.a. Amazing Grace) [Paris]
- Marie Curie [Atlantis]
- and an ordered list of all activities:
### Activities:
- 2015-11-01: **Grace Hopper** and I went to _Marie's Diner_. George had to cancel at the last minute.
- 2015-01-04: Got lunch with **Grace Hopper** and **George Washington Carver**.
- 2014-12-31: Celebrated the new year in _Paris_ with **Marie Curie**.
- 2014-11-15: Talked to **George Washington Carver** on the phone for an hour.
See the example
friends.md
file for more information.
friends
supports several global flags that can be used on any command when
specified before the name of the command, like: friends [flags] [command]
.
These flags are:
--colorless
: Disable output colorization and other effects.--debug
: Debug error messages with a full backtrace.--filename
: Set the location of the friends file to use (default: ./friends.md).
$ friends --filename ./test/tmp/friends.md clean
File cleaned: "./test/tmp/friends.md"
--quiet
: Quiet output messages.
$ friends --quiet add activity Went rollerskating with George.
$ # No output!
In addition, these flags may be used without any command:
--help
: Show the help menu. This is equivalent tofriends help
. Help menus are available for all levels of commands:
$ friends --help
$ friends list --help
$ friends list activities --help
--version
: Show thefriends
program version.
Wouldn't it be nice to be able to use friends
across all of your
devices? Hooray, you can! Just put the friends.md
file in your
Dropbox/Box Sync/Google Drive/whatever folder and use the
--filename
flag. You can even set up a Bash/Zsh/whatever alias to
do this for you, like so:
alias friends="friends --filename '~/Dropbox/friends.md'"
*Note that the command-line output is colored, which this README cannot show.
$ friends add activity Got lunch with Grace and George.
Activity added: "2015-01-04: Got lunch with Grace Hopper and George Washington Carver."
friends
will automatically figure out which "Grace" and "George" you're referring to, even if you're friends with lots of different Graces and Georges.
Nicknames will be used to match friends in activities, just like formal names:
$ friends add activity Invented debugging with The Admiral.
Activity added: "2016-01-06: Invented debugging with Grace Hopper."
You can also use the first initial of a last name instead of the whole thing.
friends
will figure out what to do with those pesky periods (if you include
them) based on whether you're in the middle of a sentence or not:
$ friends add activity Got lunch with Earnest H and Earnest S. in the park. Man, I like Earnest H. but really love Earnest S.
Activity added: "2016-05-01: Got lunch with Earnest Hemingway and Earnest Shackleton in the park. Man, I like Earnest Hemingway but really love Earnest Shackleton."
And locations will be matched as well:
$ friends add activity Went swimming near atlantis with George.
Activity added: "2016-01-06: Went swimming near Atlantis with George Washington Carver."
Tags will be colored if they're provided (though this README can't display color so you'll just have to have faith here):
$ friends add activity The office softball team wins a game! @work @exercise
Activity added: "2016-05-05: The office softball team wins a game! @work @exercise"
You can of course specify a date for the activity:
$ friends add activity Yesterday: Celebrated the new year with Marie.
Activity added: "2014-12-31: Celebrated the new year with Marie Curie."
Or get an interactive prompt by just typing friends add activity
, with or without a date specified:
$ friends add activity 2015-11-01
2015-11-01: <type description here>
Natural-language dates work just fine:
$ friends add activity last Monday
2016-03-07: <type description here>
You can escape the names of friends you don't want friends
to match with a backslash:
$ friends add activity "2015-11-01: Grace and I went to \Marie's Diner. \George had to cancel at the last minute."
Activity added: "2015-11-01: Grace Hopper and I went to Marie's Diner. George had to cancel at the last minute."
$ friends add friend Grace Hopper
Friend added: "Grace Hopper"
$ friends add tag Grace Hopper science
Tag added to friend: "Grace Hopper @science"
$ friends add location Atlantis
Location added: "Atlantis"
$ friends add nickname "Grace Hopper" "The Admiral"
Nickname added: "Grace Hopper (a.k.a. The Admiral)
$ friends add nickname "Grace Hopper" "Amazing Grace"
Nickname added: "Grace Hopper (a.k.a. The Admiral a.k.a. Amazing Grace)"
Reads and re-writes the friends.md
file:
$ friends clean
File cleaned: "./friends.md"
This command is useful after manual editing of the file, for re-ordering its contents.
Allows you to manually edit the file:
$ friends edit
Opening "./friends.md" in vim
The file is opened with the command specified by the $EDITOR
environment
variable, falling back to vim
if it is not set:
$ export EDITOR=atom
$ friends edit
Opening "./friends.md" in atom
Graphs (in color!) your activities over time:
$ friends graph
Nov 2014 |███
Dec 2014 |██
Jan 2015 |███████
Feb 2015 |█████
Or graph only activities with a certain friend:
$ friends graph --with George
Nov 2014 |█
Dec 2014 |
Jan 2015 |█████
Feb 2015 |███
Or graph only activities with a certain tag:
$ friends graph --tagged food
Nov 2014 |█
Dec 2014 |
Jan 2015 |
Feb 2015 |███
Or graph only activities in a certain location:
$ friends graph --in Paris
Nov 2014 |█
Dec 2014 |
Jan 2015 |
Feb 2015 |█
And you can use multiple of these flags together:
$ friends graph --in Paris --tagged food --with George
Nov 2014 |█
Displays a help menu. This is equivalent to friends --help
.
$ friends help
NAME
friends - Spend time with the people you care about. Introvert-tested. Extrovert-approved.
SYNOPSIS
friends [global options] command [command options] [arguments...]
...
Help menus are available for all levels of commands:
$ friends help
$ friends help list
$ friends help list activities
Lists recent activities:
$ friends list activities
2015-01-04: Got lunch with Grace Hopper and George Washington Carver. @food
2014-12-31: Celebrated the new year with Marie Curie in New York City. @partying
2014-11-15: Talked to George Washington Carver on the phone for an hour.
You can adjust how many activities are shown:
$ friends list activities --limit 2
2015-01-04: Got lunch with Grace Hopper and George Washington Carver. @food
2014-12-31: Celebrated the new year with Marie Curie in New York City. @partying
Or only list the activities you did with a certain friend:
$ friends list activities --with George
2015-01-04: Got lunch with Grace Hopper and George Washington Carver. @food
2014-11-15: Talked to George Washington Carver on the phone for an hour.
Or filter your activities by location:
$ friends list activities --in "New York"
2014-12-31: Celebrated the new year with Marie Curie in New York City. @partying
Or by tag:
$ friends list activities --tagged food
2015-01-04: Got lunch with Grace Hopper and George Washington Carver. @food
And you can mix and match these options to your heart's content:
$ friends list activities --tagged food --with Grace
2015-01-04: Got lunch with Grace Hopper and George Washington Carver. @food
Lists your "favorite" friends (by total number of activities):
$ friends list favorite friends
Your favorite friends:
1. George Washington Carver (2 activities)
2. Grace Hopper (1)
3. Marie Curie (1)
You can specify a number of favorites to show:
$ friends list favorite friends --limit 2
Your favorite friends:
1. George Washington Carver (2 activities)
2. Grace Hopper (1)
Lists your "favorite" locations (by total number of activities):
$ friends list favorite locations
Your favorite locations:
1. Atlantis (2 activities)
2. Paris (1)
3. London (1)
You can specify a number of favorites to show:
$ friends list favorite locations --limit 2
Your favorite locations:
1. Atlantis (2 activities)
2. Paris (1)
Lists all of your friends in alphabetical order:
$ friends list friends
George Washington Carver
Grace Hopper
Marie Curie
You can also include friend nicknames, locations, and tags:
$ friends list friends --verbose
George Washington Carver
Grace Hopper (a.k.a. The Admiral a.k.a. Amazing Grace) [Paris] @navy @science
Marie Curie [Atlantis] @science
You can filter your friends by location:
$ friends list friends --in Paris
Marie Curie
And you can also filter your friends by tag:
$ friends list friends --tagged science
Grace Hopper
Marie Curie
Lists all tags you've used, in alphabetical order:
$ friends list tags
@dancing
@food
@school
@swanky
You can limit this to only tags from activities:
$ friends list tags --from activities
@dancing
@food
@swanky
Or only tags from friends:
$ friends list tags --from friends
@school
@swanky
Lists all of the locations you've added, in alphabetical order::
$ friends list locations
Atlantis
New York City
Paris
Removes a specific tag from a friend:
$ friends remove tag Grace Hopper fun
Tag removed from friend: "Grace Hopper (a.k.a. Amazing Grace) @OtherTag"
Removes a specific nickname from a friend:
$ friends remove nickname "Grace Hopper" "The Admiral"
Nickname removed: "Grace Hopper (a.k.a. Amazing Grace)"
$ friends rename friend "Grace Hopper" "Grace Brewster Murray Hopper"
Name changed: "Grace Brewster Murray Hopper (a.k.a. Amazing Grace)"
$ friends rename location Paris "Paris, France"
Location renamed: "Paris, France"
Sets a friend's location:
$ friends set location Marie Paris
Marie Curie's location set to: Paris
Gives you your lifetime usage stats:
$ friends stats
Total activities: 4
Total friends: 3
Total time elapsed: 5 days
Gives you suggestions of up to three random friends to do something with, based on how often you've done things with them in the past:
$ friends suggest
Distant friend: Marie Curie
Moderate friend: Grace Hopper
Close friend: George Washington Carver
You can request suggestions of friends in a specific location:
$ friends suggest --in Paris
Distant friend: Marie Curie
Updates friends
to the latest version on RubyGems:
$ friends update
Updated to friends 0.17
In case you're really interested, we have documentation on RubyDoc.
If you have an idea, make a GitHub Issue! Suggestions are very very welcome, and usually are implemented very quickly. And if you'd like to do the implementing yourself, see the contributing guide.
A big big thanks to all of this project's lovely contributors!
Note that this project follows a Code of Conduct. If you're a polite, reasonable person you won't have any issues!
Friends is released under the MIT License.