subroutine project

The 10 commands under subroutine project, each with its arguments and options.

subroutine project [OPTIONS] COMMAND [ARGS]...

Group work into projects.

subroutine project create

subroutine project create [OPTIONS] {key} {title}

Make a project to file work under.

Examples:

subroutine project create web "Website redesign"

subroutine project create service-marketing "Marketing site" --parent web

The key is how this project is addressed here — in '+web' when you capture a line, and in its web address. Letters and digits, starting with a letter, hyphens inside but not at either end, up to 32 characters.

It is stored lower case whatever you type, so 'WEB' and 'web' are the same project and it will be shown to you as 'web'.

It can be changed later with 'subroutine project rename', which says what will stop working before it does it. Nothing already recorded moves: every item keeps its number, because a number belongs to the workspace rather than to the project.

Arguments

• key (str, required): Its short name, like 'web'. Lower case.
• title (str, required): What it is called.

Options

• --description (str): What it is for.
• --parent (str): Put it inside this project.
• --private (flag): Only you can see it, until you share it.
• --json (flag): Print the result as JSON.

subroutine project list

subroutine project list [OPTIONS]

Show the projects you can see, with what is inside what.

Examples:

subroutine project list

Options

• --json (flag): Print the list as JSON.

subroutine project rename

subroutine project rename [OPTIONS] {key} {to}

Give a project a different short name.

Examples:

subroutine project rename ST SR

The old name stops working, and nothing is left pointing at it. That is deliberate: a name you retired should be retired. Nothing already recorded moves — every item keeps its number, and what it is filed under does not change.

What does break is anything that wrote the old name down: a bookmarked address, a '.subroutine' file in a checkout, a '+OLD' in a shell history. This says so before it does it.

Arguments

• key (str, required): The project, by its current short name.
• to (str, required): Its new short name.

Options

• --yes (flag): Do not ask.

subroutine project share

subroutine project share [OPTIONS] {key} {username}

Let somebody see a private project.

Examples:

subroutine project share secret jo

This grants sight and nothing else — what they may do in the project is still their role in the workspace, so they have to be in it already.

A project inside a private one is hidden by the parent, and a membership on the child grants nothing while that is true. Sharing the parent is what opens it, and this says which project that is rather than appearing to work.

Arguments

• key (str, required): The project, by its short name.
• username (str, required): Who to let in.

subroutine project unshare

subroutine project unshare [OPTIONS] {key} {username}

Stop somebody seeing a private project.

Examples:

subroutine project unshare secret jo

The owner cannot be removed, and neither can the last person left: a private project nobody holds is one nobody can see or make public again.

Arguments

• key (str, required): The project, by its short name.
• username (str, required): Who to shut out.

subroutine project sharing

subroutine project sharing [OPTIONS] {key}

Show who can see a project.

Examples:

subroutine project sharing secret

A public project usually shows just its owner. That is not a mistake — it says who would still see it if somebody made it private, which is what anybody about to do that is asking.

Arguments

• key (str, required): The project, by its short name.

Options

• --json (flag): Print the list as JSON.

subroutine project settings

subroutine project settings [OPTIONS] {key}

Show what a project is configured with, and where each value came from.

Examples:

subroutine project settings web

A project states little of its own: most of what it shows comes from the project above it or from its workspace, and each line says which. A value set here is changed with 'subroutine project update'; one set further up is changed where it was set.

Arguments

• key (str, required): The project, by its short name.

Options

• --json (flag): Print the settings as JSON.

subroutine project update

subroutine project update [OPTIONS] {key}

Change a project's name, what it is for, who can see it, or where it stands.

Examples:

subroutine project update web --title "Website redesign"

subroutine project update web --status on_hold

Putting a project on hold leaves everything in it exactly where it is and still findable. What changes is that its work stops being offered as something to start.

Its short name is not changed here — that breaks addresses, so it has a command of its own with a warning attached: 'subroutine project rename'.

Arguments

• key (str, required): The project, by its short name.

Options

• --title (str, default '\x00not given'): What to call it.
• --description (str, default '\x00not given'): What it is for. Pass '' to clear.
• --status (str, default '\x00not given'): active, on_hold, completed or archived.
• --colour (str, default '\x00not given'): What its work is marked with: amber, green, teal, cyan, indigo, violet, magenta, slate. Pass '' to inherit.
• --hide-status (str, repeatable): A status not to offer here, e.g. 'blocked'. Repeat for more, or pass '' to inherit.
• --hide-nothing (flag): Offer every status here, whatever the workspace hides.
• --private / --public (flag): Who can see it.

subroutine project prioritise

subroutine project prioritise [OPTIONS] [key]

Raise one project's work above the rest, without hiding anybody else's.

Examples:

subroutine project prioritise web

subroutine project prioritise --none

One project per workspace, and choosing another moves it. Its work rises in ranked listings and on your agenda under Next; anything urgent or important in another project still comes first, which is the difference between this and hiding things.

With no argument it says what is prioritised here.

Arguments

• key (str): The project to raise, by name or address.

Options

• --none (flag): Stop prioritising anything here.

subroutine project move

subroutine project move [OPTIONS] {key}

Move a project, and everything underneath it, somewhere else in the tree.

Examples:

subroutine project move WEB --under ACME

subroutine project move WEB --root

Nothing is renumbered and nothing is refiled: every item keeps its number and stays in the project it was in. What moves is where that project sits.

'--under' and '--root' are the two directions and one of them has to be said. An omitted destination once meant "move to root", which flattened subtrees by accident.

Arguments

• key (str, required): The project to move, by its short name.

Options

• --under (str): Put it inside this project, by key.
• --root (flag): Make it a top-level project instead.
• --yes (flag): Do not ask.