@spec clone(String.t()) :: {:ok, String.t()} | {:error, Gitea.Error}

clone/1 clones a remote git repository based on git_repo_url returns the path of the local copy of the repository.

@spec clone(String.t(), [String.t()]) :: {:ok, String.t()} | {:error, Gitea.Error}

clone/2 clones a remote git repository based on git_repo_url. The second argument is a list of string representing where to clone the repository to. The functin returns either {:ok, path} or {:error, reason}

@spec commit(String.t(), String.t(), %{
  message: String.t(),
  full_name: String.t(),
  email: String.t()
}) ::
  {:ok, any()} | {:error, Gitea.Error}

commit/3 commits the latest changes on the local branch. Accepts the repo_name and a Map of params: params.message: the commit message you want in the log params.full_name: the name of the person making the commit params.email: email address of the person committing.

@spec create_branch(String.t(), String.t(), String.t()) ::
  {:ok, any()} | {:error, Gitea.Error}

create_branch/3 creates a branch.

inject_git/0 injects a Git TestDouble in Tests & CI so we don't have duplicate mocks in the downstream app.

@spec local_branch_create(String.t(), String.t(), String.t()) ::
  {:ok, map()} | {:error, any()}

local_branch_create/3 creates a branch with the specified name or defaults to "draft", and switch to this branch.

@spec local_file_read(String.t(), String.t(), String.t()) ::
  {:ok, String.t()} | {:error, any()}

local_file_read/3 reads the raw text from the file_name, params: org_name, repo_name & file_name

@spec local_file_write_text(String.t(), String.t(), String.t(), String.t()) ::
  {:ok, String.t()} | {:error, Gitea.Error}

local_file_write_text/3 writes the desired text, to the file_name in the repo_name. Touches the file in case it doesn't already exist.

@spec push(String.t(), String.t()) :: {:ok, any()} | {:error, any()}

push/2 pushes the org_name/repo_name (current active branch) to the remote repository URL. Mocked during test/CI.

@spec remote_org_create(%{
  :username => String.t(),
  optional(:description) => String.t(),
  optional(:full_name) => String.t(),
  optional(:visibility) => String.t()
}) :: {:ok, map()} | {:error, any()}

Create an organisation on Gitea. The second argument opts is a keyword list value and define the description, full_name and visibility

@spec remote_org_delete(String.t()) :: {:ok, map()} | {:error, any()}

Delete an organisation on Gitea.

@spec remote_read_raw(String.t(), String.t(), String.t(), String.t()) ::
  {:ok, map()} | {:error, any()}

remote_read_file/4 reads a file from the remote repo. Accepts 4 arguments: org_name, repo_name, file_name and branch_name. The 4^th argument is optional and defaults to "master" (the default branch for a repo hosted on Gitea). Makes a GET request to the remote Gitea instance as defined by the environment variable GITEA_URL. Returns {:ok, %HTTPoison.Response{ body: response_body}} Uses REST API Endpoint:

GET /repos/:username/:reponame/raw/:branchname/:path

Ref: https://github.com/gitea/docs-api/blob/master/Repositories/Contents.md#get-contents

@spec remote_render_markdown_html(String.t(), String.t(), String.t(), String.t()) ::
  {:ok, map()} | {:error, any()}

remote_render_markdown_html/4 uses Gitea built-in Markdown processor to render a Markdown Doc e.g. the README.md so you can easily use the HTML. Accepts 4 arguments: org_name, repo_name, file_name and branch_name. The 4^th argument is optional and defaults to "master" (the default branch for a repo hosted on Gitea). Makes a GET request to the remote Gitea instance as defined by the environment variable GITEA_URL. Returns {:ok, %HTTPoison.Response{ body: response_body}} Uses REST API Endpoint:

POST /markdown/raw

Ref: https://github.com/dwyl/gitea/issues/23

@spec remote_repo_create(String.t(), String.t(), boolean()) ::
  {:ok, :repo_created} | {:error, Gitea.Error}

remote_repo_create/3 accepts 3 arguments: org_name, repo_name & private. It creates a repo on the remote Gitea instance as defined by the environment variable GITEA_URL. For convenience it assumes that you only have one Gitea instance. If you have more or different requirements, please share!

@spec remote_repo_delete(String.t(), String.t()) :: {:ok, map()} | {:error, any()}

remote_repo_delete/2 accepts two arguments: org_name and repo_name. It deletes the repo on the remote Gitea instance as defined by the environment variable GITEA_URL.