Gogs (gogs v1.1.0)

Documentation for the main Gogs functions.
This package is an Elixir interface to our Gogs Server. It contains all functions we need to create repositories, clone, add data to files, commit, push and diff. Some of these functions use Git and others use the REST API. We would obviously prefer if everything was one or the other, but sadly, some things cannot be done via Git or REST so we have adopted a "hybrid" approach.

If anything is unclear, please open an issue: github.com/dwyl/gogs/issues

Link to this section Summary

Functions

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

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.

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

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

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

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.

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

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<sup>th</sup> argument is optional and defaults to "master" (the default branch for a repo hosted on Gogs). Makes a GET request to the remote Gogs instance as defined by the environment variable GOGS_URL. Returns {:ok, %HTTPoison.Response{ body: response_body}} Uses REST API Endpoint

remote_render_markdown_html/4 uses Gog 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<sup>th</sup> argument is optional and defaults to "master" (the default branch for a repo hosted on Gogs). Makes a GET request to the remote Gogs instance as defined by the environment variable GOGS_URL. Returns {:ok, %HTTPoison.Response{ body: response_body}} Uses REST API Endpoint

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

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

Link to this section Functions

Link to this function

clone(git_repo_url)

@spec clone(String.t()) :: String.t()

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

Link to this function

commit(org_name, repo_name, params)

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

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.

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

Link to this function

local_branch_create(org_name, repo_name, branch_name \\ "draft")

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

Link to this function

local_file_read(org_name, repo_name, file_name)

@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

Link to this function

local_file_write_text(org_name, repo_name, file_name, text)

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

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.

Link to this function

push(org_name, repo_name)

@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.

Link to this function

remote_read_raw(org_name, repo_name, file_name, branch_name \\ "master")

@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<sup>th</sup> argument is optional and defaults to "master" (the default branch for a repo hosted on Gogs). Makes a GET request to the remote Gogs instance as defined by the environment variable GOGS_URL. Returns {:ok, %HTTPoison.Response{ body: response_body}} Uses REST API Endpoint:

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

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

Link to this function

remote_render_markdown_html(org_name, repo_name, file_name, branch_name \\ "master")

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

remote_render_markdown_html/4 uses Gog 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<sup>th</sup> argument is optional and defaults to "master" (the default branch for a repo hosted on Gogs). Makes a GET request to the remote Gogs instance as defined by the environment variable GOGS_URL. Returns {:ok, %HTTPoison.Response{ body: response_body}} Uses REST API Endpoint:

POST /markdown/raw

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

Link to this function

remote_repo_create(org_name, repo_name, private \\ false)

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

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

Link to this function

remote_repo_delete(org_name, repo_name)

@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 Gogs instance as defined by the environment variable GOGS_URL.