feat: mention git deps in pixi build docs (#3126)

Co-authored-by: Julian Hofer <[email protected]>

Author: nichmor

docs/build/getting_started.md

@@ -22,44 +22,67 @@ The vision is to enable building of packages from source, for any language, on a
 
 ## Setting up the Manifest
 
+This is an overview of the pixi manifest using `pixi-build`.
 
-```toml
+```toml title="pixi.toml"
 --8<-- "docs/source_files/pixi_tomls/simple_pixi_build.toml:full"
 ```
 
+
+Under the `[workspace]` section, you can specify properties like the name, channels, and platforms. This is currently an alias for `project`.
+
 Since the build feature is still in preview, you have to add "pixi-build" to `workspace.preview`.
 
+
 ```toml
 --8<-- "docs/source_files/pixi_tomls/simple_pixi_build.toml:preview"
 ```
 
+
 In `package` you specify properties specific to the package you want to build.
 
 ```toml
 --8<-- "docs/source_files/pixi_tomls/simple_pixi_build.toml:package"
 ```
 
+
 Packages are built by using build backends.
 By specifying `package.build-system.build-backend` and `package.build-system.channels` you determine which backend is used and from which channel it will be downloaded.
-In this example, we are using `pixi-build-python` in order to build a Python package.
+There are different build backends. Pixi backends can describe how to build a conda package, for a certain language or build tool.
+In this example, we are using `pixi-build-python` backend in order to build a Python package.
 
 ```toml
 --8<-- "docs/source_files/pixi_tomls/simple_pixi_build.toml:build-system"
 ```
 
-1. Specifies workspace properties like the name, channels, and platforms. This is currently an alias for `project`.
-2. Since the build feature is still in preview, you have to add "pixi-build" to `workspace.preview`.
-3. We need to add our package as dependency to the workspace.
-4. In `package` you specify properties specific to the package you want to build.
-5. Packages are built by using build backends.
-   By specifying `build-system.build-backend` and `build-system.channels` you determine which backend is used and from which channel it will be downloaded.
-6. There are different build backends.
-   Pixi backends can describe how to build a conda package, for a certain language or build tool.
-   For example, `pixi-build-python`, allows building a Python package into a conda package.
-7. `simple_python` uses `hatchling` as Python build backend so this needs to be mentioned in `host-dependencies`.
-   Read up on host-dependencies in the [Dependency Types](./dependency_types.md#host-dependencies)
-8. Python PEP517 backends like `hatchling` know how to build a Python package.
-   So `hatchling` creates a Python package, and `pixi-build-python` turns the Python package into a conda package.
+
+We need to add our package `simple_python` as dependency to the workspace.
+
+`pixi` also supports `git` dependencies, allowing you to specify a `branch`, `tag`, or `rev` to pin the dependency.
+If none are specified, the latest commit on the default branch is used. The `subdirectory` is optional and specifies the location of the package within the repository.
+
+
+```toml
+--8<-- "docs/source_files/pixi_tomls/simple_pixi_build.toml:dependencies"
+```
+
+`simple_python` uses `hatchling` as Python build backend, so this needs to be mentioned in `host-dependencies`.
+
+Python PEP517 backends like `hatchling` know how to build a Python package.
+So `hatchling` creates a Python package, and `pixi-build-python` turns the Python package into a conda package.
+
+Read up on host-dependencies in the [dependency types chapter](./dependency_types.md#host-dependencies)
+
+```toml
+--8<-- "docs/source_files/pixi_tomls/simple_pixi_build.toml:host-dependencies"
+```
+
+We add `rich` as a run dependency to the package. This is necessary because the package uses `rich` during runtime.
+You can read up on run-dependencies in the [dependency types chapter](./dependency_types.md#dependencies-run-dependencies)
+
+```toml
+--8<-- "docs/source_files/pixi_tomls/simple_pixi_build.toml:run-dependencies"
+```
 
 ## CLI Commands
 Using the preview feature you can now build packages from source.

docs/source_files/pixi_tomls/simple_pixi_build.toml

@@ -37,6 +37,8 @@ hatchling = "*"
 # We add our package as dependency to the workspace
 [dependencies]
 simple_python = { path = "." }
+# pixi also support git dependencies
+boost-check = { git = "https://github.com/wolfv/pixi-build-examples", branch = "main", subdirectory = "boost-check" }
 # --8<-- [end:dependencies]
 
 # --8<-- [start:run-dependencies]