Mirrors/nushell
2
0
Fork 0
mirror of https://github.com/nushell/nushell synced 2024-12-26 13:03:07 +00:00
Code Issues Projects Releases Packages Wiki Activity

Clean up README (#5718)

Browse source 
* Clean up README

* Update CONTRIBUTING.md

* Another pass over the README. Table of contents, more install info

* add a little extra features definition

* fix Winget instructions

* Change winget instructions to nushell (easier to remember)

Co-authored-by: Darren Schroeder <343840+fdncred@users.noreply.github.com>
This commit is contained in:
Reilly Wood 2022-06-07 15:47:08 -04:00 committed by GitHub
parent c57f41e5f2
commit 56f6f683fc
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 100 additions and 172 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

25
CONTRIBUTING.md
View file

@ -1,21 +1,14 @@
# Contributing # Contributing
Welcome to nushell! Welcome to Nushell!
*Note: for a more complete guide see [The nu contributor book](https://www.nushell.sh/contributor-book/)*
For speedy contributions open it in Gitpod, nu will be pre-installed with the latest build in a VSCode like editor all from your browser.
[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/nushell/nushell)
To get live support from the community see our [Discord](https://discordapp.com/invite/NtAbbGn), [Twitter](https://twitter.com/nu_shell) or file an issue or feature request here on [GitHub](https://github.com/nushell/nushell/issues/new/choose)! To get live support from the community see our [Discord](https://discordapp.com/invite/NtAbbGn), [Twitter](https://twitter.com/nu_shell) or file an issue or feature request here on [GitHub](https://github.com/nushell/nushell/issues/new/choose)!
<!--WIP-->
## Developing ## Developing
### Set up ### Setup
This is no different than other Rust projects. Nushell requires a recent Rust toolchain and some dependencies; [refer to the Nu Book for up-to-date requirements](https://www.nushell.sh/book/installation.html#build-from-source). After installing dependencies, you should be able to clone+build Nu like any other Rust project:
```bash ```bash
git clone https://github.com/nushell/nushell git clone https://github.com/nushell/nushell
@ -28,24 +21,24 @@ cargo build
- Build and run Nushell: - Build and run Nushell:
```shell ```shell
cargo build --release && cargo run --release cargo run
``` ```
- Build and run with extra features: - Build and run with extra features. Currently extra features include dataframes and sqlite database support.
```shell ```shell
cargo build --release --features=extra && cargo run --release --features=extra cargo run --features=extra
``` ```
- Run Clippy on Nushell: - Run Clippy on Nushell:
```shell ```shell
cargo clippy --all --features=stable cargo clippy --workspace --features=extra -- -D warnings -D clippy::unwrap_used -A clippy::needless_collect
``` ```
- Run all tests: - Run all tests:
```shell ```shell
cargo test --all --features=stable cargo test --workspace --features=extra
``` ```
- Run all tests for a specific command - Run all tests for a specific command
@ -71,5 +64,5 @@ cargo build
- To view verbose logs when developing, enable the `trace` log level. - To view verbose logs when developing, enable the `trace` log level.
```shell ```shell
cargo build --release --features=extra && cargo run --release --features=extra -- --log-level trace cargo run --release --features=extra -- --log-level trace
``` ```

247
README.md
View file

@ -1,5 +1,4 @@
# README # Nushell <!-- omit in toc -->
[![Crates.io](https://img.shields.io/crates/v/nu.svg)](https://crates.io/crates/nu) [![Crates.io](https://img.shields.io/crates/v/nu.svg)](https://crates.io/crates/nu)
![Build Status](https://img.shields.io/github/workflow/status/nushell/nushell/continuous-integration) ![Build Status](https://img.shields.io/github/workflow/status/nushell/nushell/continuous-integration)
[![Discord](https://img.shields.io/discord/601130461678272522.svg?logo=discord)](https://discord.gg/NtAbbGn) [![Discord](https://img.shields.io/discord/601130461678272522.svg?logo=discord)](https://discord.gg/NtAbbGn)
@ -8,128 +7,98 @@
![GitHub commit activity](https://img.shields.io/github/commit-activity/m/nushell/nushell) ![GitHub commit activity](https://img.shields.io/github/commit-activity/m/nushell/nushell)
![GitHub contributors](https://img.shields.io/github/contributors/nushell/nushell) ![GitHub contributors](https://img.shields.io/github/contributors/nushell/nushell)
## Nushell
A new type of shell. A new type of shell.
![Example of nushell](images/nushell-autocomplete6.gif "Example of nushell") ![Example of nushell](images/nushell-autocomplete6.gif "Example of nushell")
## Table of Contents <!-- omit in toc -->
- [Status](#status)
- [Learning About Nu](#learning-about-nu)
- [Installation](#installation)
- [Philosophy](#philosophy)
- [Pipelines](#pipelines)
- [Opening files](#opening-files)
- [Plugins](#plugins)
- [Goals](#goals)
- [Progress](#progress)
- [Officially Supported By](#officially-supported-by)
- [Contributing](#contributing)
- [License](#license)
## Status ## Status
This project has reached a minimum-viable product level of quality. This project has reached a minimum-viable-product level of quality. Many people use it as their daily driver, but it may be unstable for some commands. Nu's design is subject to change as it matures.
While contributors dogfood it as their daily driver, it may be unstable for some commands.
Future releases will work to fill out missing features and improve stability.
Its design is also subject to change as it matures.
Nu comes with a set of built-in commands (listed below). ## Learning About Nu
If a command is unknown, the command will shell-out and execute it (using cmd on Windows or bash on Linux and macOS), correctly passing through stdin, stdout, and stderr, so things like your daily git workflows and even `vim` will work just fine.
## Learning more The [Nushell book](https://www.nushell.sh/book/) is the primary source of Nushell documentation. You can find [a full list of Nu commands in the book](https://www.nushell.sh/book/command_reference.html), and we have many examples of using Nu in our [cookbook](https://www.nushell.sh/cookbook/).
There are a few good resources to learn about Nu. We're also active on [Discord](https://discord.gg/NtAbbGn) and [Twitter](https://twitter.com/nu_shell); come and chat with us!
There is a [book](https://www.nushell.sh/book/) about Nu that is currently in progress.
The book focuses on using Nu and its core concepts.
If you're a developer who would like to contribute to Nu, we're also working on a [book for developers](https://www.nushell.sh/contributor-book/) to help you get started.
There are also [good first issues](https://github.com/nushell/nushell/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) to help you dive in.
We also have an active [Discord](https://discord.gg/NtAbbGn) and [Twitter](https://twitter.com/nu_shell) if you'd like to come and chat with us.
You can also find information on more specific topics in our [cookbook](https://www.nushell.sh/cookbook/).
## Installation ## Installation
### Local To quickly install Nu:
Up-to-date installation instructions can be found in the [installation chapter of the book](https://www.nushell.sh/book/installation.html). **Windows users**: please note that Nu works on Windows 10 and does not currently have Windows 7/8.1 support. ```bash
# Linux and macOS
To build Nu, you will need to use the **latest stable (1.60 or later)** version of the compiler. brew install nushell
# Windows
Required dependencies:
- pkg-config and libssl (only needed on Linux)
- On Debian/Ubuntu: `apt install pkg-config libssl-dev`
Optional dependencies:
- To use Nu with all possible optional features enabled, you'll also need the following:
- On Linux (on Debian/Ubuntu): `apt install libxcb-composite0-dev libx11-dev`
To install Nu via cargo (make sure you have installed [rustup](https://rustup.rs/) and the latest stable compiler via `rustup install stable`):
For Windows users, you may also need to install the [Microsoft Visual C++ 2015 Redistributables](https://docs.microsoft.com/cpp/windows/latest-supported-vc-redist).
```shell
cargo install nu
```
To install Nu via the [Windows Package Manager](https://aka.ms/winget-cli):
```shell
winget install nushell winget install nushell
``` ```
To install Nu via the [Chocolatey](https://chocolatey.org) package manager: Detailed installation instructions can be found in the [installation chapter of the book](https://www.nushell.sh/book/installation.html). Nu is available via many package managers:
```shell
choco install nushell
```
You can also build Nu yourself with all the bells and whistles (be sure to have installed the [dependencies](https://www.nushell.sh/book/installation.html#dependencies) for your platform), once you have checked out this repo with git:
```shell
cargo build --workspace --features=extra
```
### Packaging status
[![Packaging status](https://repology.org/badge/vertical-allrepos/nushell.svg)](https://repology.org/project/nushell/versions) [![Packaging status](https://repology.org/badge/vertical-allrepos/nushell.svg)](https://repology.org/project/nushell/versions)
#### Fedora
[COPR repo](https://copr.fedorainfracloud.org/coprs/atim/nushell/): `sudo dnf copr enable atim/nushell -y && sudo dnf install nushell -y`
## Philosophy ## Philosophy
Nu draws inspiration from projects like PowerShell, functional programming languages, and modern CLI tools. Nu draws inspiration from projects like PowerShell, functional programming languages, and modern CLI tools.
Rather than thinking of files and services as raw streams of text, Nu looks at each input as something with structure. Rather than thinking of files and data as raw streams of text, Nu looks at each input as something with structure.
For example, when you list the contents of a directory, what you get back is a table of rows, where each row represents an item in that directory. For example, when you list the contents of a directory what you get back is a table of rows, where each row represents an item in that directory.
These values can be piped through a series of steps, in a series of commands called a 'pipeline'. These values can be piped through a series of steps, in a series of commands called a 'pipeline'.
### Pipelines ### Pipelines
In Unix, it's common to pipe between commands to split up a sophisticated command over multiple steps. In Unix, it's common to pipe between commands to split up a sophisticated command over multiple steps.
Nu takes this a step further and builds heavily on the idea of _pipelines_. Nu takes this a step further and builds heavily on the idea of _pipelines_.
Just as the Unix philosophy, Nu allows commands to output to stdout and read from stdin. As in the Unix philosophy, Nu allows commands to output to stdout and read from stdin.
Additionally, commands can output structured data (you can think of this as a third kind of stream). Additionally, commands can output structured data (you can think of this as a third kind of stream).
Commands that work in the pipeline fit into one of three categories: Commands that work in the pipeline fit into one of three categories:
- Commands that produce a stream (e.g., `ls`) - Commands that produce a stream (e.g., `ls`)
- Commands that filter a stream (eg, `where type == "Dir"`) - Commands that filter a stream (eg, `where type == "Dir"`)
- Commands that consume the output of the pipeline (e.g., `autoview`) - Commands that consume the output of the pipeline (e.g., `table`)
Commands are separated by the pipe symbol (`|`) to denote a pipeline flowing left to right. Commands are separated by the pipe symbol (`|`) to denote a pipeline flowing left to right.
```shell ```shell
> ls | where type == "Dir" | autoview > ls | where type == "dir" | table
───┬────────┬──────┬───────┬────────────── ╭────┬──────────┬──────┬─────────┬───────────────╮
# │ name │ type │ size │ modified │ # │ name │ type │ size │ modified │
───┼────────┼──────┼───────┼────────────── ├────┼──────────┼──────┼─────────┼───────────────┤
0 │ assets │ Dir │ 128 B │ 5 months ago │ 0 │ .cargo │ dir │ 0 B │ 9 minutes ago │
1 │ crates │ Dir │ 704 B │ 50 mins ago │ 1 │ assets │ dir │ 0 B │ 2 weeks ago │
2 │ debian │ Dir │ 352 B │ 5 months ago │ 2 │ crates │ dir │ 4.0 KiB │ 2 weeks ago │
3 │ docs │ Dir │ 192 B │ 50 mins ago │ 3 │ docker │ dir │ 0 B │ 2 weeks ago │
4 │ images │ Dir │ 160 B │ 5 months ago │ 4 │ docs │ dir │ 0 B │ 2 weeks ago │
5 │ src │ Dir │ 128 B │ 1 day ago │ 5 │ images │ dir │ 0 B │ 2 weeks ago │
6 │ target │ Dir │ 160 B │ 5 days ago │ 6 │ pkg_mgrs │ dir │ 0 B │ 2 weeks ago │
7 │ tests │ Dir │ 192 B │ 3 months ago │ 7 │ samples │ dir │ 0 B │ 2 weeks ago │
───┴────────┴──────┴───────┴────────────── │ 8 │ src │ dir │ 4.0 KiB │ 2 weeks ago │
│ 9 │ target │ dir │ 0 B │ a day ago │
│ 10 │ tests │ dir │ 4.0 KiB │ 2 weeks ago │
│ 11 │ wix │ dir │ 0 B │ 2 weeks ago │
╰────┴──────────┴──────┴─────────┴───────────────╯
``` ```
Because most of the time you'll want to see the output of a pipeline, `autoview` is assumed. Because most of the time you'll want to see the output of a pipeline, `table` is assumed.
We could have also written the above: We could have also written the above:
```shell ```shell
> ls | where type == Dir > ls | where type == "dir"
``` ```
Being able to use the same commands and compose them differently is an important philosophy in Nu. Being able to use the same commands and compose them differently is an important philosophy in Nu.
@ -137,15 +106,13 @@ For example, we could use the built-in `ps` command to get a list of the running
```shell ```shell
> ps | where cpu > 0 > ps | where cpu > 0
───┬────────┬───────────────────┬──────────┬─────────┬──────────┬────────── ╭───┬───────┬───────────┬───────┬───────────┬───────────╮
# │ pid │ name │ status │ cpu │ mem │ virtual │ # │ pid │ name │ cpu │ mem │ virtual │
───┼────────┼───────────────────┼──────────┼─────────┼──────────┼────────── ├───┼───────┼───────────┼───────┼───────────┼───────────┤
0 │ 435 │ irq/142-SYNA327 │ Sleeping │ 7.5699 │ 0 B │ 0 B │ 0 │ 2240 │ Slack.exe │ 16.40 │ 178.3 MiB │ 232.6 MiB │
1 │ 1609 │ pulseaudio │ Sleeping │ 6.5605 │ 10.6 MB │ 2.3 GB │ 1 │ 16948 │ Slack.exe │ 16.32 │ 205.0 MiB │ 197.9 MiB │
2 │ 1625 │ gnome-shell │ Sleeping │ 6.5684 │ 639.6 MB │ 7.3 GB │ 2 │ 17700 │ nu.exe │ 3.77 │ 26.1 MiB │ 8.8 MiB │
3 │ 2202 │ Web Content │ Sleeping │ 6.8157 │ 320.8 MB │ 3.0 GB ╰───┴───────┴───────────┴───────┴───────────┴───────────╯
4 │ 328788 │ nu_plugin_core_ps │ Sleeping │ 92.5750 │ 5.9 MB │ 633.2 MB
───┴────────┴───────────────────┴──────────┴─────────┴──────────┴──────────
``` ```
### Opening files ### Opening files
@ -155,72 +122,49 @@ For example, you can load a .toml file as structured data and explore it:
```shell ```shell
> open Cargo.toml > open Cargo.toml
────────────────────┬─────────────────────────── ╭──────────────────┬────────────────────╮
bin │ [table 18 rows] │ bin │ [table 1 row] │
build-dependencies │ [row serde toml] │ dependencies │ {record 24 fields} │
dependencies │ [row 29 columns] │ dev-dependencies │ {record 8 fields} │
dev-dependencies │ [row nu-test-support] │ features │ {record 10 fields} │
features │ [row 19 columns] │ package │ {record 13 fields} │
package │ [row 12 columns] │ profile │ {record 3 fields} │
workspace │ [row members] │ target │ {record 2 fields} │
────────────────────┴─────────────────────────── │ workspace │ {record 1 field} │
╰──────────────────┴────────────────────╯
``` ```
We can pipeline this into a command that gets the contents of one of the columns: We can pipe this into a command that gets the contents of one of the columns:
```shell ```shell
> open Cargo.toml | get package > open Cargo.toml | get package
───────────────┬──────────────────────────────────── ╭───────────────┬────────────────────────────────────╮
authors │ [table 1 rows] │ authors │ [list 1 item] │
default-run │ nu │ default-run │ nu │
description │ A new type of shell │ description │ A new type of shell │
documentation │ https://www.nushell.sh/book/ │ documentation │ https://www.nushell.sh/book/ │
edition │ 2018 │ edition │ 2018 │
exclude │ [table 1 rows] │ exclude │ [list 1 item] │
homepage │ https://www.nushell.sh │ homepage │ https://www.nushell.sh │
license │ MIT │ license │ MIT │
name │ nu │ name │ nu │
readme │ README.md │ readme │ README.md │
repository │ https://github.com/nushell/nushell │ repository │ https://github.com/nushell/nushell │
version │ 0.32.0 │ rust-version │ 1.60 │
───────────────┴──────────────────────────────────── │ version │ 0.63.1 │
╰───────────────┴────────────────────────────────────╯
``` ```
Finally, we can use commands outside of Nu once we have the data we want: And if needed we can drill down further:
```shell ```shell
> open Cargo.toml | get package.version > open Cargo.toml | get package.version
0.32.0 0.63.1
``` ```
### Configuration
Nu has early support for configuring the shell. You can refer to the book for a list of [all supported variables](https://www.nushell.sh/book/configuration.html).
To set one of these variables, you can use `config set`. For example:
```shell
> config set line_editor.edit_mode "vi"
> config set path $nu.path
```
### Shells
Nu will work inside of a single directory and allow you to navigate around your filesystem by default.
Nu also offers a way of adding additional working directories that you can jump between, allowing you to work in multiple directories simultaneously.
To do so, use the `enter` command, which will allow you to create a new "shell" and enter it at the specified path.
You can toggle between this new shell and the original shell with the `p` (for previous) and `n` (for next), allowing you to navigate around a ring buffer of shells.
Once you're done with a shell, you can `exit` it and remove it from the ring buffer.
Finally, to get a list of all the current shells, you can use the `shells` command.
### Plugins ### Plugins
Nu supports plugins that offer additional functionality to the shell and follow the same structured data model that built-in commands use. Nu supports plugins that offer additional functionality to the shell and follow the same structured data model that built-in commands use. There are a few examples in the `crates/nu_plugins_*` directories.
This allows you to extend nu for your needs.
There are a few examples in the `plugins` directory.
Plugins are binaries that are available in your path and follow a `nu_plugin_*` naming convention. Plugins are binaries that are available in your path and follow a `nu_plugin_*` naming convention.
These binaries interact with nu via a simple JSON-RPC protocol where the command identifies itself and passes along its configuration, making it available for use. These binaries interact with nu via a simple JSON-RPC protocol where the command identifies itself and passes along its configuration, making it available for use.
@ -231,23 +175,19 @@ If the plugin is a sink, it is given the full vector of final data and is given
Nu adheres closely to a set of goals that make up its design philosophy. As features are added, they are checked against these goals. Nu adheres closely to a set of goals that make up its design philosophy. As features are added, they are checked against these goals.
- First and foremost, Nu is cross-platform. Commands and techniques should carry between platforms and offer consistent first-class support for Windows, macOS, and Linux. - First and foremost, Nu is cross-platform. Commands and techniques should work across platforms and Nu has first-class support for Windows, macOS, and Linux.
- Nu ensures direct compatibility with existing platform-specific executables that make up people's workflows. - Nu ensures compatibility with existing platform-specific executables.
- Nu's workflow and tools should have the usability in day-to-day experience of using a shell in 2019 (and beyond). - Nu's workflow and tools should have the usability expected of modern software in 2022 (and beyond).
- Nu views data as both structured and unstructured. It is a structured shell like PowerShell. - Nu views data as either structured or unstructured. It is a structured shell like PowerShell.
- Finally, Nu views data functionally. Rather than using mutation, pipelines act as a means to load, change, and save data without mutable state. - Finally, Nu views data functionally. Rather than using mutation, pipelines act as a means to load, change, and save data without mutable state.
## Commands
You can find a list of Nu commands, complete with documentation, in [quick command references](https://www.nushell.sh/book/command_reference.html).
## Progress ## Progress
Nu is in heavy development and will naturally change as it matures and people use it. The chart below isn't meant to be exhaustive, but rather helps give an idea for some of the areas of development and their relative completion: Nu is under heavy development and will naturally change as it matures. The chart below isn't meant to be exhaustive, but it helps give an idea for some of the areas of development and their relative maturity:
| Features | Not started | Prototype | MVP | Preview | Mature | Notes | | Features | Not started | Prototype | MVP | Preview | Mature | Notes |
| ------------- | :---------: | :-------: | :-: | :-----: | :----: | -------------------------------------------------------------------- | | ------------- | :---------: | :-------: | :-: | :-----: | :----: | -------------------------------------------------------------------- |
@ -270,20 +210,15 @@ Nu is in heavy development and will naturally change as it matures and people us
Please submit an issue or PR to be added to this list. Please submit an issue or PR to be added to this list.
### Integrations
- [zoxide](https://github.com/ajeetdsouza/zoxide) - [zoxide](https://github.com/ajeetdsouza/zoxide)
- [starship](https://github.com/starship/starship) - [starship](https://github.com/starship/starship)
- [oh-my-posh](https://ohmyposh.dev) - [oh-my-posh](https://ohmyposh.dev)
- [Couchbase Shell](https://couchbase.sh) - [Couchbase Shell](https://couchbase.sh)
- [virtualenv](https://github.com/pypa/virtualenv) - [virtualenv](https://github.com/pypa/virtualenv)
### Mentions
- [The Python Launcher for Unix](https://github.com/brettcannon/python-launcher#how-do-i-get-a-table-of-python-executables-in-nushell)
## Contributing ## Contributing
See [Contributing](CONTRIBUTING.md) for details. See [Contributing](CONTRIBUTING.md) for details. Thanks to all the people who already contributed!
Thanks to all the people who already contributed!
<a href="https://github.com/nushell/nushell/graphs/contributors"> <a href="https://github.com/nushell/nushell/graphs/contributors">
<img src="https://contributors-img.web.app/image?repo=nushell/nushell&max=500" /> <img src="https://contributors-img.web.app/image?repo=nushell/nushell&max=500" />