Skip to content

Commit

Permalink
Update readme (#42)
Browse files Browse the repository at this point in the history
- update README with details of change re. PCRE
- add travis badge & links
- fix whitespace
  • Loading branch information
OldhamMade authored Dec 25, 2018
1 parent 74d3dbc commit ea98501
Show file tree
Hide file tree
Showing 2 changed files with 62 additions and 33 deletions.
93 changes: 61 additions & 32 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,25 +1,29 @@
# `ll` - a more informative `ls`, based on [`k`][1]

[![Waffle.io - Summary](https://badge.waffle.io/03e04bd3c5dd71dd392210b4479adccc.svg?columns=all)](https://waffle.io/OldhamMade/ll)
[![Waffle.io - Summary][7]][8] [![Travis Build][9]][10]


## Description

`ll` is an alternative to [`k`][1], which was created to make directory listings more informative
and readable, using colour to add visual weight to important information in the listing.
`ll` is an alternative to [`k`][1], which was created to make
directory listings more informative and readable, using colour to add
visual weight to important information in the listing.

### Motivation

[`k`][1] only works with [`zsh`][2], and I've found that it can occasionally be a little slow
when working with large directories or with large git repositories. I was looking for a project
which would be a good match to learn/use [`nim`][3], and this seemed like a great opportunity to make
something a little more general-purpose that could be used without the [`zsh`][2] dependency.
[`k`][1] only works with [`zsh`][2], and I've found that it can
occasionally be a little slow when working with large directories or
with large git repositories. I was looking for a project which would
be a good match to learn/use [`nim`][3], and this seemed like a great
opportunity to make something a little more general-purpose that could
be used without the [`zsh`][2] dependency.

## Features

### Full file listing

Calling `ll` provides a full file listing for a directory, similar to calling `ls -l`.
Calling `ll` provides a full file listing for a directory, similar to calling
`ls -l`.

### File weight colours

Expand All @@ -29,35 +33,44 @@ Human readable files sizes can be shown by using the `-h` flag.

### "Rotting" dates

Dates fade with age, so that recently changed files/directories can be easily identified.
Dates fade with age, so that recently changed files/directories can be
easily identified.

### Broken Symlinks

Broken symlinks are identified by a `~>` (tilde-arrow) leading symbol and differing colors.
Broken symlinks are identified by a `~>` (tilde-arrow) leading symbol
and differing colors.

### Git integration

`ll` provides easy-to-understand information about the `git` status of your files/directories.
`ll` provides easy-to-understand information about the `git` status of
your files/directories.

#### Git status on entire repos

When listing a directory which contains git repos, `ll` displays the active state of those repos:
When listing a directory which contains git repos, `ll` displays the
active state of those repos:

![Image demonstrating repository listing](.images/repos.png)

#### Git status on files within a working tree

When listing files/directories within a working tree, `ll` displays the active state of each file, and the overall state for directories:
When listing files/directories within a working tree, `ll` displays
the active state of each file, and the overall state for directories:

![Image demonstrating file listing](.images/status.png)

### Speed

`ll` improves on `k`'s rendering speeds. Currently `ll` is comparable to `ls` display times when using the `--no-vcs` flag. Listing git repositories and trees take a little longer, but even with large listings with many git-tracked entries `ll` is still sub-second.
`ll` improves on `k`'s rendering speeds. Currently `ll` is comparable
to `ls` display times when using the `--no-vcs` flag. Listing git
repositories and trees take a little longer, but even with large
listings with many git-tracked entries `ll` is still sub-second.

## Installation

Binary distributions are planned, but for now it's possible to build and install using the following instructions.
Binary distributions are planned, but for now it's possible to build
and install using the following instructions.

### Requirements

Expand All @@ -66,25 +79,33 @@ Binary distributions are planned, but for now it's possible to build and install

### Steps

Firstly install [Nim][3]. You'll need to install version 0.19 as a minimum. I personally use [`asdf`][6] to manage Nim versions on my machine. With `asdf` installed, this is as simple as calling `asdf install nim v0.19.0`.
Firstly install [Nim][3]. You'll need to install version 0.19 as a
minimum. I personally use [`asdf`][6] to manage Nim versions on my
machine. With `asdf` installed, this is as simple as calling `asdf
install nim v0.19.0`.

Once Nim is installed, clone this repository. From within the cloned directory, call `make release` which will build `ll` into the working directory. Copy the resulting `ll` binary to a location in your `$PATH` (eg. `/usr/local/bin`).
Once Nim is installed, clone this repository. From within the cloned
directory, call `make release` which will build `ll` into the working
directory. Copy the resulting `ll` binary to a location in your
`$PATH` (eg. `/usr/local/bin`).

## Usage

$ ll

That's it. For more options, pass `--help`. Alternatively, read the [usage](src/usage.txt) file.

That's it. For more options, pass `--help`. Alternatively, read the
[usage](src/usage.txt) file.

## Development

`ll` is developed using Github issues and [Kanban][4] (via [Waffle][5]). If you would like to
request a feature or report a bug, please add a new issue [here](https://github.com/OldhamMade/ll/issues)
and we'll do our best to address them. Please note that this is not a funded project and fixes
will be addressed on a best-effort basis.
`ll` is developed using Github issues and [Kanban][4] (via
[Waffle][5]). If you would like to request a feature or report a bug,
please add a new issue [here](https://github.com/OldhamMade/ll/issues)
and we'll do our best to address them. Please note that this is not a
funded project and fixes will be addressed on a best-effort basis.

Contributions and pull-requests are always welcome, as is constructive feedback around
code structure, hints, tips, etc.
Contributions and pull-requests are always welcome, as is constructive
feedback around code structure, hints, tips, etc.

## Status

Expand All @@ -98,24 +119,28 @@ code structure, hints, tips, etc.
- [x] Sort output by modified time
- [x] Sort output in reversed order
- [x] Options for filtering directories
- [x] Remove dependency on PCRE (using the `regex` package)
- [ ] Installable via Homebrew
- [ ] Support light themes
- [ ] Support globs

### Fixes over [`k`][1]

* [`k`][1] has an odd behaviour; given `pwd` is a git-tracked directory, if you `k somedir` where `somedir`
contains git-tracked directories but isn't itself tracked, `k` reports as though it is working inside a
work-tree. `ll` reports this as one would expect, as though `pwd` is `somedir`. **UPDATE:** This has now
* [`k`][1] has an odd behaviour; given `pwd` is a git-tracked
directory, if you `k somedir` where `somedir` contains git-tracked
directories but isn't itself tracked, `k` reports as though it is
working inside a work-tree. `ll` reports this as one would expect, as
though `pwd` is `somedir`. **UPDATE:** This has now
[been fixed](https://github.com/supercrabtree/k/issues/47).

### Future plans

According to the [`k`][1] source, there are future plans to colorise file permissions. If this happens,
I plan to bring those changes over. If any other enhancements are added, I hope to port those also.
According to the [`k`][1] source, there are future plans to colorise
file permissions. If this happens, I plan to bring those changes
over. If any other enhancements are added, I hope to port those also.

I'd like to display some additional information in the summary line of the listing; I'm currently reviewing
what would be most useful.
I'd like to display some additional information in the summary line of
the listing; I'm currently reviewing what would be most useful.


[1]: https://github.com/supercrabtree/k
Expand All @@ -124,3 +149,7 @@ what would be most useful.
[4]: https://en.wikipedia.org/wiki/Kanban
[5]: https://waffle.io
[6]: https://github.com/asdf-vm/asdf
[7]: https://badge.waffle.io/03e04bd3c5dd71dd392210b4479adccc.svg?columns=all
[8]: https://waffle.io/OldhamMade/ll
[9]: https://api.travis-ci.org/OldhamMade/ll.svg?branch=master
[10]: https://travis-ci.org/OldhamMade/ll
2 changes: 1 addition & 1 deletion tests/path_tests.nim
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ suite "basic path tests":
test "it provides absolute paths for common shortcuts":
let
trim = (s: string) => s.strip(leading=false, chars={'/'})

check:
getTargetPath("..").trim == expandFilename(getCurrentDir() / "..").trim
getTargetPath(".").trim == getCurrentDir().trim
Expand Down

0 comments on commit ea98501

Please sign in to comment.