_,                            ,--.   ,---.
  /(_                     ,---.  `--'  /  .-'
 |   '-._        . ' .   (  .-'  ,--.  |  `-,
 \    ,-.)      -= * =- .-'  `)  |  |  |  .-'
  \((` .(        '/. '  `----'   `--'  `--'
   )\  _/        /         just like magic
.-'   '--.      /
\,         \   /|
 ';,_) _)'\ \,//
  `\   (   '._/
   |  . '.
   |      \
   |  \|   |
    \  |  /
     '.| /

Summary

sif is an intelligent curator that makes information meaningful and findable; it's a command line interface that runs as fast as you think. — Oh, she's also known as a Norse goddess.

You can, for example, call sif find tutorial and sif will display you a list of tutorial links.

sif's main focus is on sifting through and finding links. You can think of it as a command-line bookmark manager.

Read the usage examples section to learn more about what sif is capable of.

Dependencies

sif is a Node.JS command line application. So it requires a Node.JS runtime.

To install sif, you will also need npm, which comes bundled with Node.JS most of the time.

sif runs best in unix-like environments: It leverages the already superb file searching and sorting capabilities of unix, mainly egrep and sort.

Note

egrep and sort can be implemented in pure JavaScript (as streams) too; implementing these in the future, will make sif more portable and more platform-agnostic. Until then if you don't have bash, then you'll need an emulation layer to run sif.

Supported Operating Systems

Unix-Like Operating Systems

sif works well in unix, and Mac OS X.

Windows

For windows the installer will reject to install. And even if you force it by npm install sif -g --force you will get error when you're running the program.

There are open issues about that, so it'll be fixed in the future. If you feel like you can fix it faster, fix it and make a pull request; we'll love to have your help.

How to Install

Once you have node and npm installed, execute the following command to install sif:

sudo npm install sif -g

To check that sif is up and running, simply call sif on the terminal. This action will display an introductory help message.

sif

     _,
    /(_
   |   '-._        . ' .
   \    ,-.)      -= * =-
    \((` .(        '/. '
     )\  _/        /
  .-'   '--.      /
  \,         \   /|
   ';,_) _)'\ \,//


  Usage: sif [options] [command]

  … truncated …

You can get further help by executing sif help [cmd] where cmd is the command name that you want to get help.

For example, to get further help about the find command, simply type the following in the terminal:

sif help find

How to Upgrade

To update sif to the latest version run a

npm update sif -g

Caveat

Updating sif will delete your data. So make sure that you backup your global node_modules/sif/data folder before doing an update.

Upgrading will be easier in the upcoming versions; but, it's not without side effects right now.

Configuration

Currently, there are no configuration options for sif; this will change in the upcoming releases.

Usage Examples

Searching

sif find "jquery"

# You can use regular expressions too
sif find "jQuery.*css"
sif find "jQ\S*ry|atom|b..lerpl.te"

# Since this is a unix shell, you can do further filtering on the results:
sif find "jQ\S*ry|atom|b..lerpl.te" | grep boiler

Aliases

TODO:// this command has not been implemented yet.

Alias

Note

This command requires sudo access.

An alias is a single-word token with no spaces in it. Instead of typing a complicated search RegExp over and over again you can just type the search alias preceeded by an "@" sign.

For example, the following statement defines a search alias:

sudo sif alias videos "youtube\.com|vimeo\.com"

And the following statement executes a search with the defined alias:

sif find @videos

If you define an existing alias you overrite it.

# Define a search alias:
sif alias test "test"

# Update the alias:
sif alias test "test|sample"

Removing an Alias

To remove an alias use rmalis:

sif rmalias youtube

TODO:// this command is under development.

Tagging

Note

This command requires sudo access.

You can also add tags to a set of links that match a search query.

Tags can be any kind of text; try to keep your tags simple and memorable.

# Tag all links that match the "cisco.com" with 'cisco'.
sudo sif tag "cisco.com" cisco

Removing a tag

Note

This command requires sudo access.

Removing a tag is equally easy:

sudo sif rmtag "cisco.com" cisco

Updating the sif Index

Note

This command requires sudo access.

Calling sudo sif update will update the index file, amending necessary meta data if required.

Deleting Everything

Note

This command requires sudo access.

sif gets bundled with a lot of useful information and links; yet if you want to start with a blank slate, you can do so.

The easiest way to do that is to run the following in the command prompt:

sudo sif purge

Be warned that this command will delete all the data including the search index, the runbooks, the aliases, and anything else.

Getting Help

Simply typing sif, sif help, sif --help or sif h will display a help message.

You can display further help information by typing sif help [cmd]. For example, to get help about the sif find command, just type sif help find.

Hey, I'm Stuck!

For any issues that you stumble upon, feel free to open a ticket.

TODO:// Code documentation is not ready yet.

Supported Environments

sif uses builtin bash commands. So, to use it, you will either need a unix flavor such as Ubuntu or Fedora; or a fake linux like Mac OS; or a linux emulation layer like Cygwin (for Windows).

Therefore, sif runs best in unix-like environments (i.e., Mac OS, and Linux).

Note

sif is not tested thoroughly on Windows, so your experience there may vary. — If you are a Windows user, please report any issues you have so that it can be scheduled to be fixed in the upcoming releases.

Versioning and Backwards Compatibility

sif follows semantic versioning rules, and it is versioned in the "major.minor.patch" format.

• Any breaking backwards-incompatible change will increment the major version number.
• Any backwards-compatible enhancement will increment the minor version number.
• And any bug fixes that don't add extra features will increment the patch version number.

The Backstory

I am addicted to links, and I touch a substantial amount of links while I'm doing my day-to-day work.

I collect, categorize, sift through, and organize links.

And guess what? After you browser's bookmark index grows above a few tens of megabytes, using your browser becomes a burden. Your fellow browser becomes a "not-responding-and-unbearably-slow-big-fat-memory-hog".

And, believe me, that's not fun.

There are "social bookmarking as a service" websites to remedy, of course.

They, however, have their drawbacks:

These web applications require you to be online. Even if you are lucky to find an offline-enabled one, you'll still need to hit their APIs to do any meaningful work (like performing a search, for instance).

The need to be connected; and the need to use some form of graphical interface (be it the browser, or an app) introduce friction in the way you get things done.

If being interrupted by your pointy-haired boss is the worst thing that kills productivity, friction is the next worst thing on the line.

Last, but not the least, under poor network conditions there will be lots of latency when you are performing a search.

The next worst annoying thing to having your pinky toe stub in the doorway is watching a spinner a whole minute only to see a "Connection Failed" error on a slightly-grayish blank page.

sif doesn't have any of those problems:

• It has near-zero search latency because everything is stored locally.
• You don't need to push buttons to use it; you only need to type.
• It is fast, responsive, and free of distractions.

Note

Along with sifting through links, in the future it will also be possible to search within arbitrary text data (such as runbooks); however, the current focus of sif being the best program to index bookmarks locally.

Who Should Use sif?

If you love links; if you have hundreds (if not thousands) bookmarks waiting to be organized; if you have used services like pocket, xmarks, or delicious for a hope they will be good enough to sift through your links; if you love to keep your information all together, if you want to find things without hassle; and if you like the speed, beauty, and simplicity of the command line… then sif is just for you.

Wanna Help?

Contributors are more than welcome.

You can help make sif even better by:

• Suggesting new features by opening issues.
• Cleaning up open issues.
• Finding bugs in the code and creating issues for that.
• Testing sif by using it, and providing feedback.
• Forking the code, making it better, and creating pull requests.

Note

If you are planning to contribute to the source code, we won't bore you with a giant list of coding conventions :). It's your contribution that that matters.

Instead of a formal style guide, take care to maintain the existing coding style. Other than that, there's no formal contribution requirements.

If you want to dive into the code, then the following sections may be useful.

Local Development Setup

Note

In this section, we will use ~/PROJECTS/sif as the project workspace, yours could be different.

To develop sif locally, first fork it and then clone it to your development environment.

Then cd to the project folder:

cs ~/PROJECTS/sif

After that, cd to the project root do an npm install:

npm install

This will install a local development environment for sif.

Then, from the project root, execute the following command:

./devbin/prepublish.sh

Then execute:

source ./devbin/alias.sh

alias.sh will create an alias for sif that points to the sif executable in your project root (i.e., ~/PROJECTS/bin/sif.js in our case).

Note

You can also use npm link, instead of using ./devbin/alias.sh.

However, npm link will permanently replace your global sif command whereas ./devbin/alias.sh will only replace it for the development session.

You will need the .es6 files to be regularly transpiled to .js to be able to run, debug, and develop the code.

To make that easier, there is a watcher binary. If you run…

node ./devbin/watch.js

…then whenever you change an .es6 module, it will be automatically transpiled to .js.

Note

You can read more about ES6 and transpilation at Babel's documentation.

sif Internals

sif uses Linux bash file processing commands, child processes and streams to get the job done. It's a command line shell that manages a large text file.

This large text file is the index. The following section has some additional details about that.

The Index (data/index.idx)

The index is a plain text file that can be modified with your favorite text editor.

When you run a sif update this file is traversed and processed as follows:

• The lines get sorted in alphabethical order
• Some additional meta data (such as description and titles) is fetched from the web and amended to the lines.

This index file is regularly updated, and you can get the most recent version by simply running an npm update sif -g command.

Additionally, you are more than welcome to add links to it and create a pull request to get them merged back.

To do that simply…

• Fork this repository.
• Clone your forked repo.
• Add the links you want to be merged to the end of data/index.idx.
• Finally, create a pull request.

The Directory Structure

• bin: Contains commands that the global sif application uses. The sif global is an alias to bin/sif.js. — bin/sif.es6 is the entry point of the application.
• data: The index file, and the runbooks are stored here.
• data/runbooks: This is a proof of concept. It includes bite-sized instructions to manage certain technical tasks, so that you don't have to google it over and over again.
• devbin: Utility scripts that are used for developing, bundling, and publishing sif.
• lib: Helper modules that the files in bin use.
• CHANGELOG.md: A change log of what has been added recently.
• CODE_OF_CONDUCT.md: Reminds you to be nice to others.
• README.md: This readme you are looking at.
• LICENSE.md: Boring copyright stuff.

Contact Information

• Project Owner: Volkan Özçelik
• Project Website: https://github.com/v0lkan/sif

License

MIT-Licensed. — See the license file for details.

Code of Conduct

We are committed to making participation in this project a harassment-free experience for everyone, regardless of the level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality.

See the code of conduct for details.