Gogs (gogs v0.9.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.
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/3
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_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
clone(git_repo_url)
clone/1
clones a remote git repository based on git_repo_url
returns the path of the local copy of the repository.
commit(org_name, repo_name, params)
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()
inject_git/0
injects a Git
TestDouble in Tests & CI
so we don't have duplicate mocks in the downstream app.
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".
local_file_read(org_name, repo_name, file_name)
local_file_read/3
reads the raw text from the file_name
,
params: org_name
, repo_name
& file_name
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.
push(org_name, repo_name)
push/2
pushes the org_name/repo_name
(current active branch)
to the remote repository URL. Mocked during test/CI.
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/3
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
remote_repo_create(org_name, repo_name, private \\ false)
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(org_name, repo_name)
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
.