[Docs] Improve the docs regarding dstack init and repos to reflect the recent changes. (#3015)

Author: peterschmidt85

docs/docs/concepts/dev-environments.md

@@ -51,8 +51,7 @@ To open in VS Code Desktop, use this link:
 
 </div>
 
-`dstack apply` automatically provisions an instance, uploads the contents of the repo (incl. your local uncommitted changes),
-and sets up an IDE on the instance.
+`dstack apply` automatically provisions an instance and sets up an IDE on it.
 
 ??? info "Windows"
     On Windows, `dstack` works both natively and inside WSL. But, for dev environments, 
@@ -297,10 +296,10 @@ If you don't assign a value to an environment variable (see `HF_TOKEN` above),
 
 ### Files
 
-By default, `dstack` automatically mounts the [repo](repos.md) directory where you ran `dstack init` to any run configuration. 
+If you configured a [repo](repos.md), `dstack` automatically mounts its content (incl. your local changes) inside the container.
 
-However, in some cases, you may not want to mount the entire directory (e.g., if it’s too large),
-or you might want to mount files outside of it. In such cases, you can use the [`files`](../reference/dstack.yml/dev-environment.md#files) property.
+In some cases, you don’t need to mount an entire repo and can mount only specific directories. This can be done using
+[`files`](../reference/dstack.yml/task.md#_files) instead of repos.
 
 <div editor-title="examples/.dstack.yml"> 
 
@@ -351,7 +350,7 @@ $ dstack apply -f examples/.dstack.yml --no-repo
 </div>
 
 ??? info ".gitignore and .dstackignore"
-    `dstack` automatically excludes files and folders listed in `.gitignore` and `.dstackignore`.
+    If you configured a [repo](repos.md) or [files](#files), `dstack` excludes files and folders listed in `.gitignore` and `.dstackignore`.
 
     Uploads are limited to 2MB. To avoid exceeding this limit, make sure to exclude unnecessary files.
     You can increase the default server limit by setting the `DSTACK_SERVER_CODE_UPLOAD_LIMIT` environment variable.

docs/docs/concepts/repos.md

@@ -1,13 +1,18 @@
 # Repos
 
-Running a dev environment, task, or service with [`dstack apply`](../reference/cli/dstack/apply.md) in a directory
-mounts the contents of that directory to the container’s `/workflow` directory and sets it as the container’s current working directory.
-This allows accessing the directory files from within the run.
+Repos allow mounting remote Git repos with workloads.
 
-## Initialize a repo
+> Starting with 0.19.26, repos will be [configurable :material-arrow-top-right-thin:{ .external }](https://github.com/dstackai/dstack/issues/2851){:target="_blank"} in the run configuration. 
+
+For now, to mount a repo with workloads, run [`dstack init`](../reference/cli/dstack/init.md) in the repo directory, and then execute [`dstack apply`](../reference/cli/dstack/apply.md) from the same directory. 
 
-To use a directory with `dstack apply`, it must first be initialized as a repo by running [`dstack init`](../reference/cli/dstack/init.md).
-The directory must be a cloned Git repo.
+In this case, `dstack` mounts the contents of the repo to the container’s `/workflow` directory and sets it as the container’s current working directory. Note that `dstack` also includes any local changes.
+
+??? info "Files"
+    In some cases, you don’t need to mount an entire repo and can mount only specific directories. This can be done using
+    [`files`](../reference/dstack.yml/task.md#_files) instead of repos.
+
+## Initialize a repo
 
 [`dstack init`](../reference/cli/dstack/init.md) is not required if you pass `-P` (or `--repo`) to [`dstack apply`](../reference/cli/dstack/apply.md) (see below).
 
@@ -30,10 +35,6 @@ Uploads are limited to 2MB. Use `.gitignore` to exclude unnecessary files from b
 You can set the `DSTACK_SERVER_CODE_UPLOAD_LIMIT` environment variable to increase the default server limit.
 Increasing the limit is recommended only if you [configure an object storage](../guides/server-deployment.md).
 
-### Use a local directory instead of a Git repo
-
-If the directory is not a cloned Git repo, use [`files`](../reference/dstack.yml/task.md#_files).
-
 ## Specify the repo
 
 By default, `dstack apply` uses the current directory as a repo if it is already initialized.
@@ -81,12 +82,12 @@ $ dstack apply -f .dstack.yml --no-repo
 
 </div>
 
-## Store the repo on a volume
+<!-- ## Store the repo on a volume
 
 You can use [Volumes](../concepts/volumes.md) to persist repo changes without pushing them to the Git remote.
 Attach a volume to the repo directory (`/workflow`) or any of its subdirectories.
 `dstack` will clone the repo to the volume on the first run.
-On subsequent runs, `dstack` will use the repo contents from the volume instead of cloning the repo.
+On subsequent runs, `dstack` will use the repo contents from the volume instead of cloning the repo. -->
 
 ## What's next?
 

docs/docs/concepts/services.md

@@ -63,8 +63,7 @@ Model meta-llama/Meta-Llama-3.1-8B-Instruct is published at:
 
 </div>
 
-`dstack apply` automatically provisions instances, uploads the contents of the repo (incl. your local uncommitted changes),
-and runs the service.
+`dstack apply` automatically provisions instances and runs the service.
 
 If a [gateway](gateways.md) is not configured, the service’s endpoint will be accessible at
 `<dstack server URL>/proxy/services/<project name>/<run name>/`.
@@ -591,8 +590,10 @@ resources:
 
 By default, `dstack` automatically mounts the [repo](repos.md) directory where you ran `dstack init` to any run configuration. 
 
-However, in some cases, you may not want to mount the entire directory (e.g., if it’s too large),
-or you might want to mount files outside of it. In such cases, you can use the [`files`](../reference/dstack.yml/dev-environment.md#files) property.
+If you configured a [repo](repos.md), `dstack` automatically mounts its content (incl. your local changes) inside the container.
+
+In some cases, you don’t need to mount an entire repo and can mount only specific directories. This can be done using
+[`files`](../reference/dstack.yml/task.md#_files) instead of repos.
 
 <!-- TODO: Add a more relevant example -->
 
@@ -670,7 +671,7 @@ $ dstack apply -f examples/.dstack.yml --no-repo
 </div>
 
 ??? info ".gitignore and .dstackignore"
-    `dstack` automatically excludes files and folders listed in `.gitignore` and `.dstackignore`.
+    If you configured a [repo](repos.md) or [files](#files), `dstack` excludes files and folders listed in `.gitignore` and `.dstackignore`.
 
     Uploads are limited to 2MB. To avoid exceeding this limit, make sure to exclude unnecessary files.
     You can increase the default server limit by setting the `DSTACK_SERVER_CODE_UPLOAD_LIMIT` environment variable.

docs/docs/concepts/tasks.md

@@ -65,8 +65,7 @@ Launching `axolotl-train`...
 
 </div>
 
-`dstack apply` automatically provisions instances, uploads the contents of the repo (incl. your local uncommitted changes),
-and runs the commands.
+`dstack apply` automatically provisions instances and runs the task.
 
 ## Configuration options
 
@@ -463,10 +462,10 @@ If you don't assign a value to an environment variable (see `HF_TOKEN` above),
 
 ### Files
 
-By default, `dstack` automatically mounts the [repo](repos.md) directory where you ran `dstack init` to any run configuration. 
+If you configured a [repo](repos.md), `dstack` automatically mounts its content (incl. your local changes) inside the container.
 
-However, in some cases, you may not want to mount the entire directory (e.g., if it’s too large),
-or you might want to mount files outside of it. In such cases, you can use the [`files`](../reference/dstack.yml/dev-environment.md#files) property.
+In some cases, you don’t need to mount an entire repo and can mount only specific directories. This can be done using
+[`files`](../reference/dstack.yml/task.md#_files) instead of repos.
 
 <div editor-title="examples/.dstack.yml"> 
 
@@ -551,7 +550,7 @@ $ dstack apply -f examples/.dstack.yml --no-repo
 </div>
 
 ??? info ".gitignore and .dstackignore"
-    `dstack` automatically excludes files and folders listed in `.gitignore` and `.dstackignore`.
+    If you configured a [repo](repos.md) or [files](#files), `dstack` excludes files and folders listed in `.gitignore` and `.dstackignore`.
 
     Uploads are limited to 2MB. To avoid exceeding this limit, make sure to exclude unnecessary files.
     You can increase the default server limit by setting the `DSTACK_SERVER_CODE_UPLOAD_LIMIT` environment variable.

docs/docs/quickstart.md

@@ -1,27 +1,33 @@
 # Quickstart
 
 > Before using `dstack`, ensure you've [installed](installation/index.md) the server, or signed up for [dstack Sky :material-arrow-top-right-thin:{ .external }](https://sky.dstack.ai){:target="_blank"}.
-    
-## Initialize a repo
 
-Before using `dstack`'s CLI in a directory, initialize the directory as a repo with [`dstack init`](reference/cli/dstack/init.md).
+## Set up a directory
+    
+Set up a directory where you'll store you project files and `dstack` configurations.
 
 <div class="termy">
 
 ```shell
 $ mkdir quickstart && cd quickstart
-$ dstack init
 ```
 
 </div>
 
-## Apply a configuration
+> If the directory is a remote Git repo that you want to mount with workloads, run `dstack init`.
+> Starting with 0.19.26, repos will be [configurable :material-arrow-top-right-thin:{ .external }](https://github.com/dstackai/dstack/issues/2851){:target="_blank"} in the run configuration.
+
+## Run your first workload
+
+`dstack` supports three types of workloads.
 
 === "Dev environment"
 
     A dev environment lets you provision an instance and access it with your desktop IDE.
 
-    Create the following configuration file inside the repo:
+    <h3>Define a configuration</h3>
+
+    Create the following run configuration inside your project folder:
 
     <div editor-title=".dstack.yml"> 
 
@@ -42,6 +48,8 @@ $ dstack init
 
     </div>
 
+    <h3>Apply the configuration</h3>
+
     Apply the configuration via [`dstack apply`](reference/cli/dstack/apply.md):
 
     <div class="termy">
@@ -73,7 +81,9 @@ $ dstack init
 
     A task allows you to schedule a job or run a web app. Tasks can be distributed and can forward ports.
 
-    Create the following configuration file inside the repo:
+    <h3>Define a configuration</h3>
+
+    Create the following run configuration inside your project folder:
 
     <div editor-title="task.dstack.yml"> 
 
@@ -103,6 +113,8 @@ $ dstack init
     By default, tasks run on a single instance. To run a distributed task, specify 
     [`nodes`](concepts/tasks.md#distributed-tasks), and `dstack` will run it on a cluster.
 
+    <h3>Apply the configuration</h3>
+
     Run the configuration via [`dstack apply`](reference/cli/dstack/apply.md):
 
     <div class="termy">
@@ -133,7 +145,9 @@ $ dstack init
 
     A service allows you to deploy a model or any web app as an endpoint.
 
-    Create the following configuration file inside the repo:
+    <h3>Define a configuration</h3>
+
+    Create the following run configuration inside your project folder:
 
     <div editor-title="service.dstack.yml"> 
 
@@ -164,6 +178,8 @@ $ dstack init
 
     </div>
 
+    <h3>Apply the configuration</h3>
+
     Run the configuration via [`dstack apply`](reference/cli/dstack/apply.md):
 
     <div class="termy">
@@ -198,14 +214,25 @@ $ dstack init
         If you're using [dstack Sky :material-arrow-top-right-thin:{ .external }](https://sky.dstack.ai){:target="_blank"},
         a gateway is pre-configured for you.
 
-> `dstack apply` automatically provisions instances, uploads the contents of the repo (incl. your local uncommitted changes),
-and runs the configuration.
+`dstack apply` automatically provisions instances and runs the workload according to the configuration.
+
+??? info "Repo is not initialized"
+
+    If you don't run `dstack init`, you may see the following warning:
+
+    ```
+    Repo is not initialized. Use --repo <dir> or --no-repo to initialize it.
+    Starting from 0.19.26, repos will be configured via YAML and this message won't appear.
+    ```
+
+    From 0.19.26 onward, this message will no longer be shown since repos can be 
+    [configured :material-arrow-top-right-thin:{ .external }](https://github.com/dstackai/dstack/issues/2851){:target="_blank"} in the run configuration.
 
 ## Troubleshooting
 
 Something not working? See the [troubleshooting](guides/troubleshooting.md) guide.
 
 !!! info "What's next?"
-    1. Read about [backends](concepts/backends.md),  [dev environments](concepts/dev-environments.md), [tasks](concepts/tasks.md), and [services](concepts/services.md)
+    1. Read about [backends](concepts/backends.md),  [dev environments](concepts/dev-environments.md), [tasks](concepts/tasks.md), [services](concepts/services.md), and [fleets](concepts/services.md)
     2. Browse [examples](../examples.md)
     3. Join [Discord :material-arrow-top-right-thin:{ .external }](https://discord.gg/u8SmfwPpMd)