GitTools

can change coderoot with: export CODEROOT="/tmp/codetest"

Are good tools to allow you to work with GIT in a programatic way

Git repo's get checked out under

• multibranch: $homedir/code/multi/accountname/reponame/branchname/code
• single brach (default): $homedir/code/accountname/reponame/code

TODO: need to check this multibranch could be its broken

heroscript

• cmd string // clone,commit,pull,push,delete
• filter string // if used will only show the repo's which have the filter string inside
• repo string
• account string
• provider string
• msg string
• url string
• pull bool
• reset bool = true // means we will lose changes (only relevant for clone, pull)
• coderoot string //where do we want to checkout the code}

// clone,commit,pull,push,delete
!!gittools.clone coderoot:'/tmp/code' pull:true reset:true 
        url:'https://git.ourworld.tf/home/info_freeflowuniverse'

Objects

• Structure of all found gitrepo's
• GitRepo
• linked to one or more git addresses
• linked to a specific repository as its stored on the local filesystem
• links to gitstructure
• GitAddress
• links to gitstructure
• can retrieve gitrepo from it but not linked
• GitLocator
• always has GitAddress
• a gitlocator is nothing without gitaddress

get gitstructure and repo

import freeflowuniverse.crystallib.develop.gittools

coderoot := '/tmp/code_test'
mut gs := gittools.get(root: coderoot)!

mut path := gittools.code_get(
    root: coderoot
    pull: true
    reset: true    
    url: 'https://github.com/despiegk/ourworld_data'
)!

gs_default.list()!
gs.list()!

result is something like

GitRepo{
    id: 8
    path: '/Users/despiegk1/code/github/threefoldfoundation/www_examplesite'
    addr: freeflowuniverse.crystallib.gittools.GitAddr{
        provider: 'github.com'
        account: 'threefoldfoundation'
        name: 'www_examplesite'
        path: 'manual'
        branch: 'development'
        anker: ''
        depth: 0
    }
    state: ok
}

#~/code/github/threefoldfoundation/www_examplesite/manual

- bettertoken/info_bettertoken                 development             CHANGED
- despiegk/data                                master                  CHANGED
- despiegk/htmx_vweb                           master                  CHANGED
- freeflowtribe/info_thesourcecode             development             CHANGED
- freeflowuniverse/crystallib                  development_publisher3  CHANGED
- freeflowuniverse/crystaltools                development_refactor    CHANGED
- freeflowuniverse/freeflow_network            main                    CHANGED
- freeflowuniverse/home                        development             CHANGED
- freeflowuniverse/info_freeflow_internal      development             CHANGED
- freeflowuniverse/info_freeflow_pub           development             CHANGED
- freeflowuniverse/twinactions                 development             CHANGED
- omni-sphere/info_vlang                       main                    CHANGED
- ourworld-tsc/ourworld_books                  development             CHANGED
- ourworld-tsc/ourworld_digital_bank           main                    CHANGED

GIT ADDRESS

url := 'https://github.com/vlang/v/blob/master/doc/docs.md#maps'
obj := addr_get_from_url(url) or { panic('$err') }

//result ->
GitAddr{
    provider: 'github.com'
    account: 'vlang'
    name: 'v'
    path: 'doc/docs.md'
    branch: 'master'
    anker: 'maps'
    depth: 0
}

//another example starting from git@ ... url, works in same way
url := 'git@github.com:crystaluniverse/publishtools/tree/development/doc'
obj := addr_get_from_url(url) or { panic('$err') }

tocompare := GitAddr{
    provider: 'github.com'
    account: 'crystaluniverse'
    name: 'publishtools'
    path: 'doc'
    branch: 'development'
    anker: ''
    depth: 0
}

is a cool mechanism to get the unique location to a part on page from a url

USAGE OF ENV VARIABLES

if 'MULTIBRANCH' in os.environ() {
    gs.multibranch = true
}

if 'DIR_CODE' in os.environ() {
    gs.config.root = os.environ()['DIR_CODE'] + '/'
} else {
    gs.config.root ='$os.home_dir()}/code/'
}

MULTIBRANCH and DIR_CODE can be set

• multibranch means we will checkout under $homedir/code/multi/accountname/reponame/branchname/code
• in stead of $homedir/code/accountname/reponame/code

fn cachereset() !

//////CACHE

fn code_get(args CodeGetFromUrlArgs) !string

will get repo starting from url, if the repo does not exist, only then will pull . if pull is set on true, will then pull as well . url examples: .

https://github.com/threefoldtech/tfgrid-sdk-ts
https://github.com/threefoldtech/tfgrid-sdk-ts.git
git@github.com:threefoldtech/tfgrid-sdk-ts.git

# to specify a branch and a folder in the branch
https://github.com/threefoldtech/tfgrid-sdk-ts/tree/development/docs
args:
coderoot          string
gitstructure_name string = 'default' // optional, if not mentioned is default, tmp is another good one
url               string
pull   bool // will pull if this is set
reset  bool // this means will pull and reset all changes
reload bool // reload the cache

fn configreset() !

fn get(args_ GitStructureGetArgs) !GitStructure

params: .- reload bool .

fn git_dir_get(args_ GitDirGetArgs) !string

look for git dir at (.git location), if path not specified will take current path, will give error if we can't find the .git location

 params:
        path string

fn git_repo_get(args_ GitRepoGetArgs) !GitRepo

look for git dir at (.git location), . if path not specified will take current path, . will give error if we can't find the .git location . will then opern repo from that location

 params:
        path string
        coderoot string

fn locator_new(gsconfig_ GitStructureConfig, url string) !GitLocator

will use url to get git locator (is a pointer to a file, dir or part of file)

fn new(config_ GitStructureConfig) !GitStructure

configure the gitstructure . . multibranch bool . root string // where will the code be checked out . light bool = true // if set then will clone only last history for all branches . log bool // means we log the git statements . . has also support for os.environ variables .- MULTIBRANCH .

• DIR_CODE , default: ${os.home_dir()}/code/ .

fn repo_get(args CodeGetFromUrlArgs) !GitRepo

fn reset() !

reset all caches and configs, for all git repo's . can't harm, will just reload everything

struct ActionArgs {
pub mut:
	reload    bool = true
	msg       string // only relevant for commit
	branch    string
	recursive bool
}

struct CodeGetFromUrlArgs {
pub mut:
	coderoot          string
	gitstructure_name string = 'default'
	url               string
	pull              bool // will pull if this is set
	reset             bool // this means will pull and reset all changes
	reload            bool // reload the cache
}

struct GSCodeGetFromUrlArgs {
pub mut:
	path   string
	url    string
	branch string
	sshkey string
	pull   bool // will pull if this is set
	reset  bool // this means will pull and reset all changes
	reload bool // reload the cache	
}

struct GitAddr {
pub mut:
	gsconfig   &GitStructureConfig
	provider   string
	account    string
	name       string // is the name of the repository
	branch     string
	remote_url string
}

unique identification of a git repository can be translated to location on filesystem can be translated to url of the git repository online

fn (addr GitAddr) path() !pathlib.Path

return the path on the filesystem pointing to the address (is always a dir)

fn (addr GitAddr) key() string

fn (addr GitAddr) url_get() string

url_get returns the url of a git address

fn (addr GitAddr) url_ssh_get() string

fn (addr GitAddr) url_http_get() string

fn (addr GitAddr) str() string

struct GitDirGetArgs {
pub mut:
	path string
}

struct GitLinkArgs {
pub:
	gitsource string // the name of the git repo as used in gittools from the source
	gitdest   string // same but for destination
	source    string // if gitsource used, then will be append to the gitsource repo path
	dest      string // if gitdest used, then will be append to the gitfest repo path, to see where link is created
	pull      bool   // means we will pull source & destination
	reset     bool   // means we will reset changes, they will be overwritten
}

struct GitLocator {
pub mut:
	addr  &GitAddr
	path  string // path in the repo (not on filesystem)
	anker string // position in the file
}

location of a file, dir or part of file in a GitAddr

fn (mut l GitLocator) path_on_fs() !pathlib.Path

return the path on the filesystem pointing to the locator

struct GitRepo {
	id int
pub mut:
	gs   &GitStructure @[skip; str: skip]
	addr &GitAddr
	path pathlib.Path
}

fn (repo GitRepo) key() string

fn (mut repo GitRepo) load() !GitRepoStatus

fn (mut repo GitRepo) status() !GitRepoStatus

fn (mut repo GitRepo) need_pull() !bool

fn (repo GitRepo) path_relative() string

relative path inside the gitstructure, pointing to the repo

fn (mut repo GitRepo) pull_reset(args_ ActionArgs) !

pulls remote content in, will reset changes

fn (mut repo GitRepo) commit_pull_push(args_ ActionArgs) !

commit the changes, message is needed, pull from remote, push to remote

fn (mut repo GitRepo) commit_pull(args_ ActionArgs) !

commit the changes, message is needed, pull from remote

fn (mut repo GitRepo) pull(args_ ActionArgs) !

pulls remote content in, will fail if there are local changes

fn (mut repo GitRepo) rev() !string

fn (mut repo GitRepo) commit(args_ ActionArgs) !

fn (mut repo GitRepo) remove_changes(args_ ActionArgs) !

remove all changes of the repo, be careful

fn (mut repo GitRepo) push(args_ ActionArgs) !

fn (mut repo GitRepo) branch_switch(branchname string) !

fn (mut repo GitRepo) fetch_all() !

fn (mut repo GitRepo) delete() !

deletes git repository

fn (repo GitRepo) ssh_key_set(key string) !

set the key (private ssh key)

fn (repo GitRepo) sourcetree() !

open sourcetree for the git repo

fn (repo GitRepo) vscode() !

open visual studio code for repo

struct GitRepoGetArgs {
pub mut:
	gitstructure_name string = 'default'
	path              string
}

struct GitRepoStatus {
pub mut:
	need_commit bool
	need_push   bool
	need_pull   bool
	branch      string
	remote_url  string
}

struct GitStructure {
pub mut:
	config   GitStructureConfig // configuration settings
	rootpath pathlib.Path = pathlib.get('${os.home_dir()}/code') // path to root code directory
	repos    []&GitRepo // repositories in gitstructure
	loaded   bool
}

fn (gs GitStructure) cache_reset() !

remove cache

fn (mut gitstructure GitStructure) check() !

fn (mut gs GitStructure) code_get(args_ GSCodeGetFromUrlArgs) !string

will get repo starting from url, if the repo does not exist, only then will pull . if pull is set on true, will then pull as well . url examples: .

https://github.com/threefoldtech/tfgrid-sdk-ts
https://github.com/threefoldtech/tfgrid-sdk-ts.git
git@github.com:threefoldtech/tfgrid-sdk-ts.git

# to specify a branch and a folder in the branch
https://github.com/threefoldtech/tfgrid-sdk-ts/tree/development/docs

args:
path   string
url    string
branch string
sshkey string
pull   bool // will pull if this is set
reset  bool // this means will pull and reset all changes
reload bool // reload the cache

fn (mut gs GitStructure) do(args_ ReposActionsArgs) !string

do group actions on repo args

 cmd      string // clone,commit,pull,push,delete,reload,list,edit,sourcetree,cd
 filter   string // if used will only show the repo's which have the filter string inside
 repo     string
 account  string
 provider string
 msg      string
 url      string
 pull     bool
 script   bool = true // run non interactive
 reset    bool = true // means we will lose changes (only relevant for clone, pull)

fn (mut gitstructure GitStructure) list(args ReposGetArgs) !

fn (mut gitstructure GitStructure) load() !

the factory for getting the gitstructure git is checked uderneith $/code

fn (mut gs GitStructure) locator_new(url string) !GitLocator

will use url to get git locator (is a pointer to a file, dir or part of file)

fn (gs GitStructure) name() string

fn (mut gs GitStructure) repo_add(args GSCodeGetFromUrlArgs) !&GitRepo

add repository to gitstructure

fn (mut gitstructure GitStructure) repo_exists(l GitLocator) !bool

fn (mut gitstructure GitStructure) repo_get(args_ RepoGetArgs) !GitRepo

will get repo starting from url, if the repo does not exist, only then will pull if pull is set on true, will then pull as well

fn (mut gitstructure GitStructure) repos_get(args_ ReposGetArgs) []GitRepo

fn (mut gitstructure GitStructure) repos_print(args ReposGetArgs) !

struct GitStructureConfig {
pub mut:
	name        string = 'default'
	multibranch bool
	root        string // where will the code be checked out, root of code, if not specified comes from context
	light       bool = true // if set then will clone only last history for all branches		
	log         bool // means we log the git statements
	singlelayer bool // all repo's will be on 1 level
}

struct GitStructureGetArgs {
pub mut:
	coderoot string
	name     string = 'default'
	reload   bool
}

struct RepoGetArgs {
pub mut:
	locator GitLocator
	pull    bool // if we want to pull when calling the repo
	reset   bool // if we want to force a clean repo
}

struct ReposActionsArgs {
pub mut:
	cmd       string // clone,commit,pull,push,delete,reload,list,edit,sourcetree
	filter    string // if used will only show the repo's which have the filter string inside
	repo      string
	account   string
	provider  string
	msg       string
	url       string
	branch    string
	recursive bool
	pull      bool
	script    bool = true // run non interactive
	reset     bool = true // means we will lose changes (only relevant for clone, pull)
}

struct ReposGetArgs {
pub mut:
	filter   string // if used will only show the repo's which have the filter string inside
	name     string
	account  string
	provider string
}

get a list of repo's which are in line to the args

fn (a ReposGetArgs) str() string