casey / just Goto Github PK

README.md is probably long enough to have sections with headings and a table of contents.

Macports is easy, since I'm already the maintainer of the just package. I'm not sure if just meets the notability clause to be accepted to homebrew.

Edit: @Ezku added just to homebrew

It would be really nice to support Windows users. However, just currently calls sh explicitly, which isn't available on Windows.

Some ideas:

1. Use the sh provided by the ubuntu subsystem in Windows 10
2. Allow using cmd.exe or powershell on windows
3. Write a sh in rust that runs on every platform

3 is probably the best solution, but also the most work.

Should we use "//" for comments instead of "#"?

Rust uses "//" comments so it might be nice for rust users. Also, according to this stack overflow survey, most of the popular languages with the exceptions of Python and Ruby use "//" comments.

On the other hand, using "#" is compatible with make files, so we can use makefile syntax highlighting. Also, just feels kind of scripty, which makes me like "#".

Seems like a reasonable restriction to lift. I was annoyed by it at least once.

Often times recipes have very long names, like install-dev-dependencies.

It might be nice if just could allow you to run these recipes with less typing.

One idea is to have a wildcard character:

some-long-recipe:
  @echo Doing stuff...

strip-binary:
  @echo Stripping binary...

$ just so~
Doing stuff...
$ just s~
error: `s~` is ambiguous, possibilities are `some-long-recipe` and `strip-binary`

Like so:

$ j --evaluate
a   = "something"
ab  = "something else"
foo = "h"

Can use \:

foo:
  echo some very long line that keeps on going \
    > hello

Or extra indentation, since it is otherwise illegal:

foo:
  echo some very long line that keeps on going
    > hello

As a justfile grows in commands and complexity it would be cool if we were able to generate help text like: just --browse

And maybe this could sweep the justfile and print a quick summary of all the commands and their arguments in a sorted fashion.

There are two types of error, Error and RunError.

Errors occur during tokenizing, parsing, and verification of justfiles.

RunErrors occur when you actually to run a justfile.

Since Error is not very descriptive, it should probably be renamed to something like CompileError.

It would be nice to support multi-line strings that don't automatically terminate when a newline reached.

The normal ' and " could be multi line strings, we could use ''' and """ like python, or we could use r(#*)"..."(#*) like rust.

Using the following file as your justfile

check-fmt:
        cargo fmt -- --write-mode=diff

check-rst:
        rst check

#check-build:
#        cargo check

check: check-rst check-fmt check-build

we get this error when calling just check

$ just check
thread 'main' panicked at 'no entry found for key', ../src/libcore/option.rs:700
stack backtrace:
   1:     0x55b5d8271da9 - std::sys::backtrace::tracing::imp::write::hd4b54a4a2078cb15
   2:     0x55b5d827991c - std::panicking::default_hook::_{{closure}}::h51a5ee7ba6a9fcef
   3:     0x55b5d8278bc9 - std::panicking::default_hook::hf823fce261e27590
   4:     0x55b5d8279258 - std::panicking::rust_panic_with_hook::h8d486474663979b9
   5:     0x55b5d82790b2 - std::panicking::begin_panic::h72862f004a4942ab
   6:     0x55b5d8279020 - std::panicking::begin_panic_fmt::hdc424a357d9142e1
   7:     0x55b5d8278fa1 - rust_begin_unwind
   8:     0x55b5d82b185f - core::panicking::panic_fmt::h6b06f78ae7f9dd57
   9:     0x55b5d82b18d5 - core::option::expect_failed::h523d2fa497e63fbd
  10:     0x55b5d81ababa - just::parse::h8f0dd96c3d7b13d8
  11:     0x55b5d818f10c - just::app::app::h705317bbebf49d66
  12:     0x55b5d8281406 - __rust_maybe_catch_panic
  13:     0x55b5d8278342 - std::rt::lang_start::hca48e539ce72a288
  14:     0x7fda04d0c290 - __libc_start_main
  15:     0x55b5d81850e9 - _start
  16:                0x0 - <unknown>

To avoid making this a backwards incompatible change, only strings and backticks preceeded by an f will allow interpolation:

bar := "world"
foo := f"Hello, {{bar}}!"
baz :=  f`echo "Hello, {{bar}}"`

Both foo and baz evaluate to Hello, world!.

I've marked this as "good first issue", but it's quite hard! I am very happy to mentor, provide support, and do some pair programming sessions if someone wants to tackle this.

One of the reasons that this is hard is because it will be possible to nest interpolations recursively:

qux := f"{{f"{{f"{{bar}}"}}"}}"

So the lexer might need to be modified to have a state stack to track interpolations.

Currently, just will barf if you do something like just -l hello/bar/. This is because -l is incompatible with supplying a recipe. However, in this case it seems reasonable since the argument is not a recipe, but a path to start searching for the justfile.

Allow supplying a single path-only recipe with arguments like --dump, --edit, and --list

Noticed this in the clap-rs justfile:

update-contributors:
	@echo 'Removing old CONTRIBUTORS.md'
	@mv CONTRIBUTORS.md CONTRIBUTORS.md.bak
	@echo 'Downloading a list of new contributors'
	@echo "The following is a list of contributors in alphabetical order:" > CONTRIBUTORS.md
	@echo "" >> CONTRIBUTORS.md
	@echo "" >> CONTRIBUTORS.md
	@githubcontrib --owner kbknapp --repo clap-rs --sha master --cols 6 --format md --showlogin true --sortBy login >> CONTRIBUTORS.md
	@rm CONTRIBUTORS.md.bak

I've done the same thing myself a few times, so it might be nice to mark a recipe as quiet, and then flip the meaning of "@" in that recipe:

@update-contributors:
	echo 'Removing old CONTRIBUTORS.md'
	mv CONTRIBUTORS.md CONTRIBUTORS.md.bak
	echo 'Downloading a list of new contributors'
	echo "The following is a list of contributors in alphabetical order:" > CONTRIBUTORS.md
	echo "" >> CONTRIBUTORS.md
	echo "" >> CONTRIBUTORS.md
	githubcontrib --owner kbknapp --repo clap-rs --sha master --cols 6 --format md --showlogin true --sortBy login >> CONTRIBUTORS.md
	rm CONTRIBUTORS.md.bak

Not sure if this is a good idea or not. It's not hard to prefix all lines of a recipe with "@".

This applies to OSX but is likely a general question:

Given a recipe such as:

goog query:
  @open http://google.com/search?q={{query}}

It would seem this can't be invoked with a single string argument that has spaces within it as in the following:

just goog "how to train your dragon"

Is there a way to accomplish this that I'm missing? Thanks again.

Depends on #1340 if accepted

I've already written a few bugs due to not testing different OSes more thoroughly.

A few things have been to blame:

• case sensitive vs insensitive filesystems
• sh being bash in some places and dash in others

It would be nice to add support for easily spinning up a Debian VM and FreeBSD VM, and installing and testing just to avoid future issues.

Currently, a shebang recipe can use arguments in the same way as a command recipe:

recipe ARGUMENT:
  #!/usr/bin/env python3
  print("{{ARGUMENT}}")

$ just recipe HELLO
HELLO

It might be nice to also invoke the script with those arguments, so that the recipe can access them in the usual way for that language:

recipe ARGUMENT:
  #!/usr/bin/env python3
  import sys
  print(sys.argv[1])

This way you don't need to think about how literal text substitution will work, for example if there are special characters or newlines in the argument.

It might also be a good idea to export arguments to command recipes as well:

recipe ARGUMENT:
  echo $ARGUMENT

You could also export them as environment variables to shebang recipes:

recipe ARGUMENT:
  #!/usr/bin/env python3
  import os
  print(os.getenv('ARGUMENT'))

From @fuine's comment in #7.

I'm still trying to figure out whether coloring or highlighting the run command is a good idea or not.

it's good when there's a ton of output and you want to find what command it came from, or which command is currently running.

But it's not so good when there's not a lot of output and the output is what you care about, since then it distracts from the output.

Currently, j relies on a make or gmake command being available. This causes some problems:

• Only trivial justfiles are likely to be portable across flavors of make
• Running j on windows is difficult
• Since it is a j "feature" that flags are passed to make, it can't have flags of its own
• Makefile syntax only allows leading tabs
• Make won't run a recipe if there is a file with same name as the recipe. The current workaround is to add a .PHONY directive to the justfile
• Exported variables on one line of a make recipe are not available on subsequent lines

It may be desirable to stop depending on make and move to a j-specific custom file format. This would mean that make's features would no longer be available, but a workaround to this would be to write a Makefile and call make from j.

Possible improvements this would allow:

• Add a --list flag that lists the available recipes
• Work on windows
• Relax the rule on tabs vs spaces, and just enforce that the same number of tabs and spaces precede each line of recipe
• Figure out a sane way of allowing justfiles in subdirectories

The exact syntax is up in the air, but I personally very much like the current syntax, and would like to do something similar.

Just neet to configure Travis and AppVeyor as shown here:

https://github.com/japaric/rust-everywhere

Just doesn't complain if you supply give arguments with --evaluate, but they aren't used, so better to disallow them. Especially since it's conceivable that --evaluate may eventually take a variable name to evaluate.

Always nice!

just doesn't expose a library API, but it would still be nice to add some comments to the source code, especially where something tricky or unintuitive is happening.

This would help people understand the code, both for learning and contribution purposes.

Also add a lint to complain if items don't have comments.

If there is a comment on the line preceding a recipe, it should be consider to be a doc comment that describes the recipe, and displayed with --list

# do foo
foo bar:

# bazzify
baz hello="2":

# run tests
test:

$ j --summary
baz hello="2" # bazzify
foo bar       # doo foo
test          # run tests

Since doc-comments use #, just like ordinary comments, users might give commands doc-comments accidentally.

For example:

# build commands:
build:
    do-stuff

The build gets the # build commands: doc-comment here, even though it wasn't intended. We could use ## for doc-comments to avoid this.

Add a option which allows running a command from the project root:

# for example, to edit your Cargo.toml file from any subdirectory of your project
$ just --cmd vim Cargo.toml

Would be nice to know how much of the code is exercised in tests, and what code currently isn't tested.

tarpaulin looks good.

Maybe a dumb idea, but might be nice if --edit would invoke $EDITOR on the current justfile.

Cargo allows one to specify a build rust file as explained here: http://doc.crates.io/build-script.html.

I really like the idea behind this because I'm coming from C++ / makefile land, so I totally understand 'just,' what I'm wondering what just can do that cargo's build scripting cannot do. If nothing, then I'm not sure of its utility. If something, then it should be noted in the documentation.

I didn't read the entire documentation, so maybe it already is, but it wasn't obvious. Great idea though.

They are sadly missing from the docs.

I've been looking for something along these lines for a looooong time and wanted to get your opinion on the following feature request:

How about supporting default arguments in this form:

tail-env env=green:
  @echo 'Tailing with {{env}}...'

This way, it could be invoked without the argument and will use the default specified like so:

$> just tail-env   #automatically uses green

vs

$> just tail-env blue #overrides with blue

Now that make is gone, there are some useful features that j no longer supports.

This justfile uses variables to cut down on boilerplate and improve readability. It also uses the device variable to let the user configure which device should be used:

nexus5  = 3d8569a787ad6
nexus7  = 44f60ceb5f75b
nexus6p = e1d267ee8d22d
nexus5x = 31e82532ef348
s7      = 3dbc633f55736

device = $(s7)

adb = adb -s $(device)
app = buz.fizbuz.android.dev

grant: 
    $(adb) shell pm grant $(app) android.permission.ACCESS_FINE_LOCATION
    $(adb) shell pm grant $(app) android.permission.CAMERA
    $(adb) shell pm grant $(app) android.permission.GET_ACCOUNTS
    $(adb) shell pm grant $(app) android.permission.WRITE_EXTERNAL_STORAGE
    $(adb) shell pm grant $(app) android.permission.READ_EXTERNAL_STORAGE

The compile recipe below uses arguments passed from the command line to select which subprojects to invoke compile in:

compile:
    for ARG in $$ARGS; do cd $$ARG; just compile ; cd $$WORKSPACE; done

And finally, this justfile fragment uses make's $(shell ...) syntax to set a local variable to the result of a shell command:

localhost = $(shell dumpinterfaces | cut -d: -f2 | sed 's/\/.*//' | sed 's/ //g')

To summarize, there are three desirable features here:

1. Allowing variables to be set and used in multiple recipes
2. Allowing arguments to be passed in on the command line
3. Allowing variables to be set to the output of a command invocation

These features should probably be designed together, since they'll all affect the same areas of a justfile's syntax. The syntax for setting variables at the top level will affect 1 and 2, and the syntax for variable substitution will be shared by all of them.

There are currently only a handful of tests for errors.

However, error formatting and display is complex, and making sure that the right errors are returned for the right reasons is very important.

So, it would be nice to add integration tests for as many run errors and compile errors as possible.

(Note that InternalErrors can't be tested for, since they should only be triggerable if there's a bug in the code.)

Some error messages start with a capital letter and some don't. I think that they should all start with uppercase letters, both for consistency and to help guide the user's eye.

You no longer need to manually update your version! Super nice :)

.version(env!("CARGO_PKG_VERSION"))

This might be slightly outside the originally intended use-case, but I am trying to use a justfile to automate sorting of tv shows that I rip/download

Originally I had a shell script that did this, there I used sed to extract the show, season and episode info from filenames, and stored them in separate variables. However, it seems that I cannot assign to variable within recipes

filename = "Assigning Variables here works"

sort:
    show = "Assigning Variables here doesnt work"
    @echo {{show}} # This tells me 'error: variable `show` not defined'

This feels like an obvious feature to have

j can be used to run whatever commands happen to be installed.

It would be nice if there was a mode where only binaries installed with cargo would be run, since this would mean that commands would be the same across systems.

The user could also supply a manifest of cargo binaries to install, along with their versions, in a just.toml file, so different users could make sure they had the same versions.

This is a crazy amount of work, but it would be pretty cool to have a system-independent rust/cargo based userland.

So that you don't have to build every time you make a change

Would look like this:

foo *stuff:
  @echo {{stuff}}

$ just foo a     b    c   d
a b c d

Using + may be more accurate, since I don't think I want to allow zero arguments, unless a default is supplied.

This would be a multi-line token, so it would mean that some assumptions in the tokenizer and parser would need to be revisited.

• just ../foo invokes ../justfile:foo
• just xyz/foo invokes xyz/justfile:foo
• just xyz/ invokes xyz/justfile:DEFAULT
• path prefix is starting dir, so just ../foo will invoke ../../justfile:foo if there is no justfile in ..
• how does this interact with overrides? just a=b/hello
• what about multiple recipes that have paths?
• should we handle them directly or invoke multiple instances of just?

Running things in parallel is always dangerous, but if there are many slow running jobs it might be nice.

It's probably wise to wait for user feedback on this one, to avoid doing a bunch of work for a feature nobody wants.

https://github.com/barosl/homu

If the first recipe in a justfile takes parameters, then it will be impossible to invoke it as the default recipe.

We should probably disallow the first recipe in a file from taking parameters. Or at least disallow it from having any parameters without defaults.

I often forget to run clippy since it's a separate step.

I think a quick terminalcast is probably the best way to convey what just does.

• make a new folder
• cd into that folder
• start a new project
• initialize a rust project
• demonstrate every feature
• show error messages

Ideally causing a test failure if a lint fails