In lorenzwalthert/teamtools: Tools to organize multiple git repos under a project and team umbrella

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

teamtools

r teamtools::read_local_description()

```{bash, eval = FALSE} team |- project 1 | |- repository 1 | |- repository 2 |- project 2 |- repository 3 |- repository 4

You can install teamtools from GitHub:
```r
remotes::install_github("lorenzwalthert/teamtools")

library(teamtools)

The aforementioned project structure is common for teams working on BitBucket. Every repository is technically an independent git repo. If you use another remote git client you can anyways organize different repos in projects under a team root. Note the following additional requirements:

• A team root is characterized by a directory having a .team.yaml file.
• A repository is a directory that is the root of a git repository. You may initialize git but never commit anything, e.g. if the repository is a pure data repository without git lfs.
• There must not be any nested git repositories.
• All directories directly under the root are project directories and there is only one layer between the team root and the repositories.

file navigation

You can easily list all repos or projects:

ls_repos()
ls_projects()

You can open a repo's RStudio Project, either in the current or a new session:

open_repo("meta", newSession = FALSE)

Obviously, you can also open all projects:

purrr::walk(ls_repos()$repo, open_repo)

git

teamtools helps you to check all repos for uncommitted or staged changes and untracked files. I.e. it does a git status across all your repos in your team:

teamtools::team_check_status()
#> # A tibble: 7 x 5
#>   file                                   repo            project   type   dir   
#>   <chr>                                  <chr>           <chr>     <chr>  <chr> 
#> 1 05-keras.Rmd                           lessons-learned companion untra… /User…
#> 2 bookdown-demo.Rmd                      lessons-learned companion untra… /User…
#> 3 02-analysis/02-model-decision-tree.Rmd titanic         companion untra… /User…
#> 4 pull-all-draft.R                       sandbox84       meta      unsta… /User…
#> 5 R/git.R                                teamtools       meta      unsta… /User…
#> 6 README.Rmd                             teamtools       meta      unsta… /User…
#> 7 README.md                              teamtools       meta      unsta… /User…

You may also want to know which repos' active branch are out of sync with their remote counterpart:

teamtools::team_check_unpushed()
#> For the follwing files of the current branches are not even with upstreams:
#> # A tibble: 1 x 4
#>   file    repo      project path                                                                 
#>   <chr>   <chr>     <chr>   <chr>                                                                
#>  1 R/git.R teamtools meta    /Users/lorenz/…

You can also pull from and push all team repos to their default remote branch with teamtools::team_push() and teamtools::team_pull():

teamtools::team_pull(credentials = team_credentials())
#> Try pulling lessons-learned ✔ 
#> Try pulling titanic ✔ 
#> Try pulling data ✔ 
#> Try pulling meta ✔ 
#> Try pulling sandbox84 [updated] 85e6da1024..71818fdb5a refs/remotes/origin/master ✔ 

This works via ssh. The .team.yaml contains directives where the corresponding keys are stored. You can read them with

read_team_config()

And create a corresponding ssh credential object used with git2r with team_credentials(), which is used by team_push() and team_pull() by default.

common .Rprofile

The idea is to use a common .Rprofile for all repos under a team root. Technically, you can simply source the .Rprofile from the team root in each repository's .Rprofile, which is - in simple terms - what teamtools::init_team_repo() does.

cat(teamtools:::contents_rprofile(), sep = "\n")

In addition, teamtools::init_team_repo() also initializes the .description file (see below).

README structuring

teamtools suggests that a repository's description is stored in .description. Such a description is a concise statement about what the content / goal of the repository is. This description may be used in the Rmd README by placing r teamtools::read_and_markdown_description_files(category = "repo") (enclosed in back ticks) anywhere in the README to import the description. You can use markdown syntax in the .description as this will be placed into the README as is before compiled with Pandoc. Projects can also have such descriptions, and they can be read with the above command, setting category = "project".

The description at the top of this readme was generated with this method.

---

The advantage of this approach is that these short descriptions can be accessed easily programmatically, much easier than if we had to parse a README and extract the first paragraph or something like that. You can easily retrieve all descriptions from all repos in all projects with

teamtools::read_description_files()

#>  # A tibble: 8 x 4
#>  project   repo            desc                                        class
#>  <chr>     <chr>           <chr>                                       <chr>
#> 1 companion NA              This repo contains things I learned throug… proj…
#> 4 companion lessons-learned This repo contains things I learned throug… repo 
#> 5 companion titanic         "In this repo, the famous titanic data set… repo 
#> 8 meta      sandbox84       This repository is a s sandbox repo for th… repo 

Note that this works if your current working directory is any directory under the team root.

In the future, we aim to support files other than .description to represent other meta data.

Utilities

There are a bunch of other utility functions:

find_repo_root()
find_team_root()
read_description_file("project-1", "repository-1")
read_local_description()

lorenzwalthert/teamtools documentation built on Dec. 10, 2019, 2:11 a.m.