[docs] Add source control code references docs (#22319)

## Summary

Expands the code references guide to include info on attaching
references to git source control on cloud and OSS.

## Test Plan

Vercel.

---------

Co-authored-by: Sandy Ryza <[email protected]>

docs/content/guides/dagster/code-references.mdx

@@ -27,11 +27,11 @@ To complete the steps in this guide, you'll need:
 
 ---
 
-## Automatically attaching code references to asset definitions
+## Automatically attaching local file code references to asset definitions
 
 ### Assets defined in Python
 
-To automatically attach code references to Python assets' function definitions, you can use the `dagster._core.definitions.metadata.with_source_code_references` utility. Any asset definitions passed to the utility will have their source file attached as metadata.
+To automatically attach code references to Python assets' function definitions, you can use the <PyObject module="dagster" object="with_source_code_references"/> utility. Any asset definitions passed to the utility will have their source file attached as metadata.
 
 ```python file=/guides/dagster/code_references/with_source_code_references.py
 from dagster import Definitions, asset, with_source_code_references
@@ -65,7 +65,7 @@ Dagster's dbt integration can automatically attach references to the SQL files b
 
 ---
 
-## Manually attaching code references to asset definitions
+## Manually attaching local file code references to asset definitions
 
 In some cases, you may want to manually attach code references to your asset definitions. Some assets may have a more complex source structure, such as an asset whose definition is spread across multiple Python source files or an asset which is partially defined with a `.sql` model file.
 
@@ -113,3 +113,127 @@ Each of the code references to `manual_references.py` will be visible in the **A
     height={604}
   />
 </center>
+
+---
+
+## Converting code references to link to a remote git repository
+
+In a local context, it is useful to specify local code references in order to navigate directly to the source code of an asset. However, in a production environment, you may want to link to the source control repository where the code is stored.
+
+### In Dagster Plus
+
+If using Dagster Plus, you can use the `link_code_references_to_git_if_cloud` utility to conditionally convert local file code references to source control links. This utility will automatically detect if your code is running in a Dagster Cloud environment and convert local file code references to source control links, pointing at the commit hash of the code running in the current deployment.
+
+<!-- Dagster cloud packages not built into docs image yet, hence why this is included inline -->
+
+```python
+import os
+from pathlib import Path
+
+from dagster_cloud.metadata.source_code import link_code_references_to_git_if_cloud
+
+from dagster import (
+    AnchorBasedFilePathMapping,
+    Definitions,
+    asset,
+    with_source_code_references,
+)
+
+
+@asset
+def my_asset(): ...
+
+
+@asset
+def another_asset(): ...
+
+
+defs = Definitions(
+    assets=link_code_references_to_git_if_cloud(
+        assets_defs=with_source_code_references([my_asset, another_asset]),
+        # Inferred from searching for .git directory in parent directories
+        # of the module containing this code - may also be set explicitly
+        file_path_mapping=AnchorBasedFilePathMapping(
+            local_file_anchor=Path(__file__),
+            file_anchor_path_in_repository="src/repo.py",
+        ),
+    )
+)
+```
+
+### In any Dagster environment
+
+The <PyObject module="dagster" object="link_code_references_to_git"/> utility allows you to convert local file code references to source control links. You'll need to provide the base URL of your git repository, the branch or commit hash, and a path to the repository root locally.
+
+```python file=/guides/dagster/code_references/link_to_source_control.py
+from pathlib import Path
+
+from dagster import (
+    AnchorBasedFilePathMapping,
+    Definitions,
+    asset,
+    link_code_references_to_git,
+    with_source_code_references,
+)
+
+
+@asset
+def my_asset(): ...
+
+
+@asset
+def another_asset(): ...
+
+
+defs = Definitions(
+    assets=link_code_references_to_git(
+        assets_defs=with_source_code_references([my_asset, another_asset]),
+        git_url="https://github.com/dagster-io/dagster",
+        git_branch="main",
+        file_path_mapping=AnchorBasedFilePathMapping(
+            local_file_anchor=Path(__file__),
+            file_anchor_path_in_repository="src/repo.py",
+        ),
+    )
+)
+```
+
+You may choose to conditionally apply this transformation based on the environment in which your Dagster code is running. For example, you could use an environment variable to determine whether to link to local files or to a source control repository:
+
+```python file=/guides/dagster/code_references/link_to_source_control_conditional.py
+import os
+from pathlib import Path
+
+from dagster import (
+    AnchorBasedFilePathMapping,
+    Definitions,
+    asset,
+    link_code_references_to_git,
+    with_source_code_references,
+)
+
+
+@asset
+def my_asset(): ...
+
+
+@asset
+def another_asset(): ...
+
+
+assets = with_source_code_references([my_asset, another_asset])
+
+defs = Definitions(
+    assets=link_code_references_to_git(
+        assets_defs=assets,
+        git_url="https://github.com/dagster-io/dagster",
+        git_branch="main",
+        file_path_mapping=AnchorBasedFilePathMapping(
+            local_file_anchor=Path(__file__),
+            file_anchor_path_in_repository="src/repo.py",
+        ),
+    )
+    if bool(os.getenv("IS_PRODUCTION"))
+    else assets
+)
+```

examples/docs_snippets/docs_snippets/guides/dagster/code_references/link_to_source_control.py

@@ -0,0 +1,30 @@
+from pathlib import Path
+
+from dagster import (
+    AnchorBasedFilePathMapping,
+    Definitions,
+    asset,
+    link_code_references_to_git,
+    with_source_code_references,
+)
+
+
+@asset
+def my_asset(): ...
+
+
+@asset
+def another_asset(): ...
+
+
+defs = Definitions(
+    assets=link_code_references_to_git(
+        assets_defs=with_source_code_references([my_asset, another_asset]),
+        git_url="https://github.com/dagster-io/dagster",
+        git_branch="main",
+        file_path_mapping=AnchorBasedFilePathMapping(
+            local_file_anchor=Path(__file__),
+            file_anchor_path_in_repository="src/repo.py",
+        ),
+    )
+)

examples/docs_snippets/docs_snippets/guides/dagster/code_references/link_to_source_control_conditional.py

@@ -0,0 +1,35 @@
+import os
+from pathlib import Path
+
+from dagster import (
+    AnchorBasedFilePathMapping,
+    Definitions,
+    asset,
+    link_code_references_to_git,
+    with_source_code_references,
+)
+
+
+@asset
+def my_asset(): ...
+
+
+@asset
+def another_asset(): ...
+
+
+assets = with_source_code_references([my_asset, another_asset])
+
+defs = Definitions(
+    assets=link_code_references_to_git(
+        assets_defs=assets,
+        git_url="https://github.com/dagster-io/dagster",
+        git_branch="main",
+        file_path_mapping=AnchorBasedFilePathMapping(
+            local_file_anchor=Path(__file__),
+            file_anchor_path_in_repository="src/repo.py",
+        ),
+    )
+    if bool(os.getenv("IS_PRODUCTION"))
+    else assets
+)

python_modules/dagster/dagster/_core/definitions/metadata/source_code.py

@@ -301,7 +301,7 @@ def link_code_references_to_git(
     Example:
         .. code-block:: python
                 defs = Definitions(
-                    assets=link_to_git(
+                    assets=link_code_references_to_git(
                         with_source_code_references([my_dbt_assets]),
                         git_url="https://github.com/dagster-io/dagster",
                         git_branch="master",