> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# onimur/common-tools

Collection of tools to help create commands, jobs and workflows.
Check the repository above for more details. Feel free to send any questions, suggestions or contributions to this orb.
Tools:
persist-dir and attach-dir: Facilitates interaction with the persist_to_workspace and attach_workspace commands.
git-config, git-checkout and git-push: Tools that help interact with git commands.


## Commands

### attach-dir

Get the parameters in /tmp/.persist/custom-directory.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `custom-directory` | string | persist | The name of the directory that was created to store your files or folders. If custom-directory was passed in the persist-to-dir command, then it is necessary to pass the same dir in the custom-directory.
 |
| `destination` | string |  | The destination that wants to restore the files or directories. E.g. ./my-persist-files. If empty, files or directories will be restored to your Working Directory, in the persist folder.
 |
| `paths` | string |  | The path to files or directories you want to restore. If it is empty, any files or directories that have been persisted will be recovered.
 |

### git-checkout

Checkout branch


| Parameter | Type | Default | Description |
|---|---|---|---|
| `branch` | string | master | Branch to checkout
 |

### git-config

Push the files to github


| Parameter | Type | Default | Description |
|---|---|---|---|
| `bot-email` | string | circleci@bot-noreply.com | Email to commit
 |
| `bot-name` | string | circleci-bot | User name to commit
 |

### git-push

Push the files or d to github


| Parameter | Type | Default | Description |
|---|---|---|---|
| `bot-email` | string | circleci@bot-noreply.com | Email to commit
 |
| `bot-name` | string | circleci-bot | User name to commit
 |
| `branch` | string | master | Branch to push the files
 |
| `commit-message` | string | Auto Update | Commit message |
| `paths` | string |  | Output files or directories. If it is more than one then separate it with commas.
 |
| `project` | env_var_name | CIRCLE_PROJECT_REPONAME | Name of project on GitHub.
 |
| `push-force` | boolean | false | Force the push |
| `token` | env_var_name | GITHUB_TOKEN | To make push to github remote
 |
| `user` | env_var_name | CIRCLE_PROJECT_USERNAME | Username of the owner of target GitHub repo.
 |

### persist-dir

Save files or directories.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `custom-directory` | string | persist | The name of the directory that will be created to store your files or folders.
 |
| `paths` | string |  | The path to files or directories you want to store.
 |

## Examples

### example-git-commands

Push files or folders to remote Github repository


```yaml
jobs:
  push-to-git:
    machine: true
    steps:
      - tools/git-checkout:
          branch: master
      - run:
          command: |
            mkdir -p second
            echo "Hello world!" >> hello.txt
            echo "Hello world, again!" >> second/hello-again.txt
          name: Create a file.
      - tools/git-config
      - tools/git-push:
          paths: hello.txt, second
orb_promotion_filters:
  branches:
    ignore: /.*/
  tags:
    only: /.*/
orbs:
  tools: onimur/common-tools@x.y.z
version: 2.1
workflows:
  prepare-workflows:
    jobs:
      - push-to-git:
          filters:
            branches:
              ignore: /.*/
            tags:
              only: /.*/
```

### example-persist-attach

Persist file or dir to a folder and attach.


```yaml
jobs:
  prepare:
    machine: true
    steps:
      - run:
          command: |
            mkdir -p second
            echo "Hello world!" >> hello.txt
            echo "Hello world, again!" >> second/hello-again.txt
          name: Create a file.
      - tools/persist-dir:
          paths: hello.txt, second
  recover-files:
    machine: true
    steps:
      - tools/attach-dir
      - run:
          command: |
            cat "./persist/hello.txt"
            cat "./persist/second/hello-again.txt"
          name: Get the file
orbs:
  tools: onimur/common-tools@x.y.z
version: 2.1
workflows:
  prepare-workflows:
    jobs:
      - prepare
      - recover-files:
          requires:
            - prepare
```