Better step input descriptions (#197)

* Reorder inputs and categories * Remove category of merge_pr * Remove PR ID input * Remove input from config too * Better step input descriptions * YAML lint * Reorder inputs and categories (#195) * Reorder inputs and categories * Remove category of merge_pr * Remove PR ID input (#196) * Remove PR ID input * Remove input from config too * Reorder inputs and categories * Fix step.yml after broken merge resolution * Remove category * Revert accidentally readded step input
bitrise-steplib · Jan 3, 2023 · f6f5637 · f6f5637
1 parent 2fa9d20
commit f6f5637
Show file tree

Hide file tree

Showing 2 changed files with 75 additions and 68 deletions.
diff --git a/README.md b/README.md
@@ -2,28 +2,27 @@
 
 [![Step changelog](https://shields.io/github/v/release/bitrise-steplib/steps-git-clone?include_prereleases&label=changelog&color=blueviolet)](https://github.com/bitrise-steplib/steps-git-clone/releases)
 
-The Step checks out the defined repository state, optionally updates the repository submodules and exports the achieved git repository state properties.
+Checks out the repository, updates submodules and exports git metadata as Step outputs.
 
 <details>
 <summary>Description</summary>
 
-The checkout process depends on the checkout properties: the Step either checks out a repository state defined by a git commit or a git tag, or achieves a merged state of a pull / merge request.
-The Step uses two solutions to achieve the merged state of the pull / merge request: auto merge in the case of a merge branch or diff file (provided by the Git service) and manual merge otherwise.
-Once the desired state is checked out, the Step optionally updates the submodules. In the case of pull / merge request, the Step checks out a detach head and exports the achieved git state properties.
+The checkout process depends on the Step settings and the build trigger parameters (coming from your git server).
 
-### Configuring the Step
+Depending on the conditions, the step can checkout:
+- the merged state of a Pull Request
+- the head of a Pull Request
+- a git tag
+- a specific commit on a branch
+- the head of a branch
+
+The Step also supports more advanced features, such as updating submodules and sparse checkouts.
 
-1. The **Git repository URL** and the ** Clone destination (local)directory path** fields are required fields and are automatically filled out based on your project settings.
-Optionally, you can modify the following fields in the **Clone Config** section:
-1. You can set the **Update the registered submodules?** option to `yes` to pull the most up-to-date version of the submodule from the submodule's repository.
-2. You can set the number of commits you want the Step to fetch in the **Limit fetching to the specified number of commits** option. Make sure you set a decimal number.
+### Configuring the Step
 
-Other **Clone config** inputs are not editable unless you go to the **bitrise.yml** tab, however, to avoid issues, we suggest you to contact our Support team instead.
+The step should work with its default configuration if build triggers and webhooks are set up correctly.
 
-### Troubleshooting
-If you have GitHub Enterprise set up, it works slightly differently on [bitrise.io](https://www.bitrise.io) than on [github.com](https://github.com). You have to manually set the git clone URL, register the SSH key and the webhook.
-If you face network issues in the case of self-hosted git servers, we advise you to contact our Support Team to help you out.
-If you face slow clone speed, set the **Limit fetching to the specified number of commits** to the number of commits you want to clone instead of cloning the whole commit history or you can use the Git LFS solution provided by the git provider.
+By default, the Step performs a shallow clone in most cases (fetching only the latest commit) to make the clone fast and efficient. If your workflow requires a deeper commit history, you can override this using the **Clone depth** input.
 
 ### Useful links
 
@@ -33,8 +32,7 @@ If you face slow clone speed, set the **Limit fetching to the specified number o
 ### Related Steps
 
 - [Activate SSH key (RSA private key)](https://www.bitrise.io/integrations/steps/activate-ssh-key)
-- [Bitrise.io Cache:Pull](https://www.bitrise.io/integrations/steps/cache-pull)
-- [Bitrise.io Cache:Push](https://www.bitrise.io/integrations/steps/cache-push)
+- [Generate changelog](https://bitrise.io/integrations/steps/generate-changelog)
 
 </details>
 
@@ -51,40 +49,39 @@ You can also run this step directly with [Bitrise CLI](https://github.com/bitris
 
 | Key | Description | Flags | Default |
 | --- | --- | --- | --- |
-| `repository_url` | SSH or HTTPS URL of the repository to clone | required | `$GIT_REPOSITORY_URL` |
+| `merge_pr` | This only applies to builds triggered by pull requests.  Options: - `yes`: Depending on the information in the build trigger, either fetches the PR merge ref or creates the merged state locally. - `no`: Checks out the head of the PR branch without merging it into the destination branch. |  | `yes` |
 | `clone_into_dir` | Local directory where the repository is cloned | required | `$BITRISE_SOURCE_DIR` |
+| `clone_depth` | Limit fetching to the specified number of commits.  By default, the Step tries to do a shallow clone (depth of 1) if it's possible based on the build trigger parameters. If it's not possible, it applies a low depth value, unless another value is specified here.  It's not recommended to define this input because a shallow clone ensures fast clone times. Examples of when you want to override the clone depth:  - A Step in the workflow reads the commit history in order to generate a changelog - A Step in the workflow runs a git diff against a previous commit |  |  |
+| `update_submodules` | Update registered submodules to match what the superproject expects. If set to `no`, `git fetch` calls will use the `--no-recurse-submodules` flag. |  | `yes` |
+| `submodule_update_depth` | When updating submodules, limit fetching to the specified number of commits. The value should be a decimal number, for example `10`. |  |  |
+| `fetch_tags` | yes - fetch all tags from the remote by adding `--tags` flag to `git fetch` calls no - disable automatic tag following by adding `--no-tags` flag to `git fetch` calls |  | `no` |
+| `sparse_directories` | Limit which directories to clone using [sparse-checkout](https://git-scm.com/docs/git-sparse-checkout). This is useful for monorepos where the current workflow only needs a subfolder.  For example, specifying `src/android` the Step will only clone: - contents of the root directory and - contents of the `src/android` directory and all of its subdirectories On the other hand, `src/ios` will not be cloned.  This input accepts one path per line, separate entries by a linebreak. |  |  |
+| `repository_url` | SSH or HTTPS URL of the repository to clone | required | `$GIT_REPOSITORY_URL` |
 | `commit` | Commit SHA to checkout |  | `$BITRISE_GIT_COMMIT` |
 | `tag` | Git tag to checkout |  | `$BITRISE_GIT_TAG` |
 | `branch` | Git branch to checkout |  | `$BITRISE_GIT_BRANCH` |
 | `branch_dest` | The branch that the pull request targets, such as `main` |  | `$BITRISEIO_GIT_BRANCH_DEST` |
-| `pull_request_id` | Pull request number, coming from the Git provider |  | `$PULL_REQUEST_ID` |
 | `pull_request_repository_url` | URL of the source repository of a pull request.  This points to the fork repository in builds triggered by pull requests. |  | `$BITRISEIO_PULL_REQUEST_REPOSITORY_URL` |
 | `pull_request_merge_branch` | Git ref pointing to the result of merging the PR branch into the destination branch. Even if the source of the PR is a fork, this is a reference to the destination repository.  Example: `refs/pull/14/merge`  Note: not all Git services provide this value. |  | `$BITRISEIO_PULL_REQUEST_MERGE_BRANCH` |
 | `pull_request_head_branch` | Git ref pointing to the head of the PR branch. Even if the source of the PR is a fork, this is a reference to the destination repository.  Example: `refs/pull/14/head`  Note: not all Git services provide this value. |  | `$BITRISEIO_PULL_REQUEST_HEAD_BRANCH` |
-| `update_submodules` | Update the registered submodules to match what the superproject expects by cloning missing submodules, fetching missing commits in submodules and updating the working tree of the submodules. If set to "no" `git fetch` calls will get the `--no-recurse-submodules` flag. |  | `yes` |
-| `clone_depth` | Limit fetching to the specified number of commits. The value should be a decimal number, for example `10`. |  |  |
-| `submodule_update_depth` | Truncate the history to the specified number of revisions. The value should be a decimal number, for example `10`. |  |  |
-| `merge_pr` | Disables merging the source and destination branches. - `yes`: The default setting. Merges the source branch into the destination branch. - `no`: Treats Pull Request events as Push events on the source branch. |  | `yes` |
-| `sparse_directories` | Limit which directories should be cloned during the build. This could be useful if a repository contains multiple platforms, so called monorepositories, and the build is only targeting a single platform. For example, specifying "src/android" the Step will only clone: - contents of the root directory and - contents of the "src/android" directory and all subdirectories of "src/android". On the other hand, "src/ios" and any other directories will not be cloned. |  |  |
 | `reset_repository` | Reset repository contents with `git reset --hard HEAD` and `git clean -f` before fetching. |  | `No` |
-| `fetch_tags` | yes - fetch all tags from the remote by adding `--tags` flag to git fetch calls no - disable automatic tag following by adding `--no-tags` flag to git fetch calls |  | `no` |
 | `build_url` | Unique build URL of this build on Bitrise.io |  | `$BITRISE_BUILD_URL` |
 | `build_api_token` | The build's API Token for the build on Bitrise.io | sensitive | `$BITRISE_BUILD_API_TOKEN` |
 </details>
 
 <details>
 <summary>Outputs</summary>
 
-| Environment Variable               | Description                                                                                                                                                                                                                        |
-|------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `GIT_CLONE_COMMIT_HASH`            | SHA hash of the checked-out commit.                                                                                                                                                                                                |
-| `GIT_CLONE_COMMIT_MESSAGE_SUBJECT` | Commit message of the checked-out commit.                                                                                                                                                                                          |
-| `GIT_CLONE_COMMIT_MESSAGE_BODY`    | Commit message body of the checked-out commit.                                                                                                                                                                                     |
-| `GIT_CLONE_COMMIT_COUNT`           | Commit count after checkout.  Count will only work properly if no `--depth` option is set. If `--depth` is set then the history truncated to the specified number of commits. Count will **not** fail but will be the clone depth. |
-| `GIT_CLONE_COMMIT_AUTHOR_NAME`     | Author of the checked-out commit.                                                                                                                                                                                                  |
-| `GIT_CLONE_COMMIT_AUTHOR_EMAIL`    | Email of the checked-out commit.                                                                                                                                                                                                   |
-| `GIT_CLONE_COMMIT_COMMITTER_NAME`  | Committer name of the checked-out commit.                                                                                                                                                                                          |
-| `GIT_CLONE_COMMIT_COMMITTER_EMAIL` | Email of the checked-out commit.                                                                                                                                                                                                   |
+| Environment Variable | Description |
+| --- | --- |
+| `GIT_CLONE_COMMIT_HASH` | SHA hash of the checked-out commit. |
+| `GIT_CLONE_COMMIT_MESSAGE_SUBJECT` | Commit message of the checked-out commit. |
+| `GIT_CLONE_COMMIT_MESSAGE_BODY` | Commit message body of the checked-out commit. |
+| `GIT_CLONE_COMMIT_COUNT` | Commit count after checkout.  Count will only work properly if no `--depth` option is set. If `--depth` is set then the history truncated to the specified number of commits. Count will **not** fail but will be the clone depth. |
+| `GIT_CLONE_COMMIT_AUTHOR_NAME` | Author of the checked-out commit. |
+| `GIT_CLONE_COMMIT_AUTHOR_EMAIL` | Email of the checked-out commit. |
+| `GIT_CLONE_COMMIT_COMMITTER_NAME` | Committer name of the checked-out commit. |
+| `GIT_CLONE_COMMIT_COMMITTER_EMAIL` | Email of the checked-out commit. |
 </details>
 
 ## 🙋 Contributing