.. default-domain:: bash

============
New J.U.S.T.
============

.. file:: new_just

Create a new just project

There are many moving pieces to set up a working just project and use
all the features. Just getting started is hard, without knowing where to
start. This script will create all the files necessary to have a new
docker compose based just project up and running.

.. rubric:: Usage

By default, :file:`new_just` will prompt the user for questions on the initial
setup parameters. Default values are supplied for all questions, and enter
can be pressed to accept all the defaults. All of the questions can be set
using environment variables, making them scriptable.

After :file:`new_just` is called, a few git commands need to be called. This is not
done for you, in case it will break your existing repository. These
commands are printed out on stdout, while everything else is printed on
stderr, making them scriptable.

If any of the files written to exist, they are not overwritten, and a warning
message is printed out.

.. seealso::

  :env:`new_just new_just PROJECT_DIR`, :env:`new_just new_just PROJECT_NAME`, :env:`new_just new_just PROJECT_PREFIX`
  :env:`new_just new_just REPO_NAME`, :env:`new_just new_just JUSTFILE`, :env:`new_just new_just SETUPFILE`
  :env:`new_just new_just VSI_DIR`

.. function:: docker_add_quote_escape

Escapes arbitrary filename for ``Dockerfile`` ``ADD ["filename", "dest"]`` syntax, not including outer ``"``

:Arguments: ``$1`` - Filename to be escaped

.. function:: docker_env_quote_escape

Escapes arbitrary value for ``Dockerfile`` ``ENV var="value"`` syntax, not including outer ``"``

:Arguments: ``$1`` - Value to be escaped

.. function:: new_just

The main new_just function. The script to be in a function, or else streaming ``curl`` to bash won't work.

.. env:: PROJECT_DIR

The project directory is typically the root directory of the main git
repository. This is where all the just files will be stored by default.

The value can be customized when prompted by :file:`new_just`. The default value
is the current working directory. The question can be skipped by setting
the environment variable :env:`PROJECT_DIR` to the desired value.

.. env:: PROJECT_NAME

The :env:`PROJECT_NAME` is used to set the project environment file name used by
:func:`just_functions.bsh source_environment_files`. Specifically: ``${PROJECT_DIR}/${PROJECT_NAME}.env``
:env:`PROJECT_NAME` is also used for for determining other default values.

The value can be customized when prompted by :file:`new_just`. The default value
is basename of the :env:`PROJECT_DIR`. The question can be skipped by setting the
environment variable :env:`PROJECT_NAME` to the desired value.

.. seealso::
  :func:`just_functions.bsh source_environment_files`

.. env:: PROJECT_PREFIX

The prefix of environment variables for this project

Used to set the value of :envvar:`JUST_PROJECT_PREFIX`. Must contain only valid bash
variable-name characters: ``[A-Z0-9_]+``

Does not need the trailing _ included, this will always be added when it is
used.

The value can be customized when prompted by new_just. The default value is
uppercase of the :env:`PROJECT_NAME`. The question can be skipped by setting the
environment variable :env:`PROJECT_PREFIX` to the desired value.

.. seealso::

  :envvar:`JUST_PROJECT_PREFIX`

.. env:: JUSTFILE

Name of the justfile used

The default just file in just is "Justfile". If this is changed, the only
way to inform just of this is by setting it in the :env:`SETUPFILE`. This will be
added to the :env:`SETUPFILE` by :file:`new_just` if anything other than the default is
used.

The value can be customized when prompted by :file:`new_just`. The default value
is ``Justfile``. The question can be skipped by setting the environment variable
:env:`JUSTFILE` to the desired value.

.. seealso::

  :env:`SETUPFILE`, just/Justfile

.. env:: USE_VSI_COMMON

Flag to include vsi_common

vsi_common can either be included as a submodule, in which case setup.env
is needed, or the just executable needs to be installed and vsi_common is
not needed.

.. env:: SETUPFILE

Name of the setup file sourced to setup just environment

The setup file is used to make the minimal necessary changes to the
environment so that just works. This includes adding paths and setting a
few environment variables. This is meant to be as unobtrusive as possible.

This file needs to be sourced every time a new terminal session is opened.
The only time the setup script is not needed is when using :command:`juste`.

The value can be customized when prompted by :file:`new_just`. The default value is
``setup.env``. The question can be skipped by setting the environment variable
:env:`SETUPFILE` to the desired value.

.. seealso::

  :command:`juste`

.. env:: VSI_DIR

Location of the vsi_common submodule

The vsi_common repository is necessary for virtually all of the just
capabilities. The correct way to deal with this is to add vsi_common as a
submodule for your main project. This tells just were this submodule is
located.

The value can be customized when prompted by :file:`new_just`. The default value is
external/vsi_common. The question can be skipped by setting the environment
variable :env:`VSI_DIR` to the desired value.

.. rubric:: Docker Stuff

.. env:: USE_DOCKER

Flag to turn on all the docker features

.. env:: USE_PIP_TOOLS

Flag to turn on setting up pip-tools

.. env:: APP_NAME

The name of the test app generated. Used for the name of the first service populated for you.

.. env:: REPO_NAME

When docker images are built, they need to be named, or else the only way to
access them is inconveniently though sha256 checksums.

The :env:`REPO_NAME` should be an untagged docker repository name. Tag names will
be added for each service. Docker image names must match the regex
``[a-zA-Z0-9][a-zA-Z0-9_.-]*`` or else docker will error

The value can be customized when prompted by :file:`new_just`. The default value is
lowercase of the :env:`PROJECT_NAME`. The question can be skipped by setting the
environment variable :env:`REPO_NAME` to the desired value.

.. env:: PYTHON_PACKAGE

Name of the default python package created

.. env:: USE_TUTORIAL

Flag to turn on tutorial comments