YEAR: 2019 122 | COPYRIGHT HOLDER: Danielle Navarro 123 |124 | 125 |
Copyright (c) 2019 Danielle Navarro
124 |Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
125 |The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
126 |THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
127 |A second function of workbch is to keep track of the git status of various projects. A common workflow problem (for me, at least) is that I sometimes forget to commit changes or push them upstream, and then forget which projects I’ve left in this “unclean” state. The job_gitreport() function aims to make this easier by checking the git status for all jobs, and reporting those jobs that are not in a clean state. For example:
# A tibble: 3 x 6
108 | jobname staged unstaged untracked ahead behind
109 | <chr> <int> <int> <int> <int> <int>
110 | 1 conjunction 0 1 1 3 0
111 | 2 psychtheory 0 0 1 0 0
112 | 3 tidylsrbook 0 24 12 0 0Screencast illustrating how job_gitreport() works:
A third function of the workbch package is keeping track of job locations when they move around on the local machine, as long as they stay somewhere on the workbch search path (i.e., the “workbch.search” option). It does this by matching information stored in the “.workbch” sentinel file to entries in the “workbch_jobs.json” file. There are two functions that are useful for this:
120 |job_list() throws a warning if a job folder has movedjob_seek() will ask if you want to update the locationThis is illustrated in the screencast below:
127 | 128 |A common task is to update the information associated with a job. The priority may change, it may be assigned a new owner or acquire a new URL, etc. The job_modify() function can be used for this, as illustrated below:
Danielle Navarro. Author, maintainer. 
124 |
R/job_gitreport.R
123 | job_gitreport.RdReport the git status of all jobs
129 | 130 |job_gitreport(show_clean = FALSE)133 | 134 |
| show_clean | 139 |should clean repositories be included in the output? |
140 |
|---|
A tibble with columns jobname, staged, unstaged,
146 | untracked, ahead and behind. The jobname column is
147 | a character vector, all others are integer valued.
The role of the git_report() function is to provide an overview
152 | of the status of all workbch jobs that are associated with a git repository.
153 | For every job, it uses git2r::in_repository to determine if the job
154 | folder (i.e., the path for that job) is in a git repository. Jobs that are
155 | not in git repositories are ignored.
For jobs that are associated with git repositories, the git_report()
157 | function calls git2r::status() to determine the git status. If there is an
158 | upstream set (i.e., git2r::branch_get_upstream() detects an upstream
159 | repository), it will also call git2r::ahead_behind() to determine how many
160 | commits the local repository is ahead and/or behind of the upstream.
By default, no output is shown for clean repositories (show_clean = FALSE).
162 | A repository is deemed to be clean if there are no staged, unstaged or
163 | untracked files and it is neither ahead nor behind the upstream repository.
164 | If the user specifies show_clean = TRUE, then results are reported for every
165 | job that is linked to a git repository.
R/job_glimpse.R
123 | job_glimpse.RdView the information stored about a job
129 | 130 |job_glimpse(jobname = NULL)133 | 134 |
| jobname | 139 |Name of the job to show (defaults to the current job) |
140 |
|---|
Invisibly returns the job as a list
146 | 147 |The job_glimpse() function displays parameter values for the
150 | job specified in the jobname argument. If no argument is specified
151 | job_glimpse() will attempt to guess the "current" job by looking at
152 | any open RStudio projects. If no project is open (or the RStudio API is not
153 | available) it attempts to guess by looking at the working directory. The
154 | output is presented to the user as a message.
Path to the job home
129 | 130 |job_home(jobname = NULL)133 | 134 |
| jobname | 139 |Name of job (defaults to current job) |
140 |
|---|
Path to the job folder as a character string
146 | 147 |The job_home() function returns the file path for `jobname`.
150 | This can be useful if you need to specify the location of files relative to
151 | a project.
If no argument is specified job_home() will attempt to guess the
153 | current job by looking at any open RStudio projects. If no project is open
154 | or the RStudio API is not available it attempts to guess by looking at the
155 | working directory.
View a list of all jobs
129 | 130 |job_list(search = NULL, select = c("jobname", "owner", "priority", 133 | "status", "description"))134 | 135 |
| search | 140 |input query used to extract a subset of jobs |
141 |
|---|---|
| select | 144 |character vector of columns to return |
145 |
An object of class worbch_tbl. It is regular tibble with a slightly 151 | modified print method that ensures all rows are printed in the output
152 | 153 |The job_list() function is used to display a summary of the
156 | jobs known to workbch, shown as a tibble with one row per job. By default
157 | only those jobs with a priority value of 1 or 2 will be shown, and
158 | only if their status is "active" or "inactive". Jobs that do not have
159 | sufficient priority or whose status is "complete", "abandoned" or "masked"
160 | are not shown.
The default behaviour can be overridden by specifying a search string (or
162 | object that can be coerced to a string). If the user specifies a value to
163 | search then job_list() attempts to match the search string with a parameter
164 | value. For instance job_list("active") will return all jobs that have status
165 | active and job_list(1) will return all jobs that have priority 1. At
166 | present this functionality requires that the search string be an exact value
167 | (e.g., search = "Dani" would not match a job owned by "Danielle"),
168 | though this may be extended in the future.
The output is returned to the user as a tibble, and by default the columns
170 | displayed are jobname, owner, priority, status,
171 | and description. The user can directly specify which columns to be
172 | included using the select argument, which should be a character vector
173 | specifying the names of the columns to include. In addition to the five
174 | columns made available by default, the output can include the path,
175 | tags and urls associated with the job. For convenience, if you
176 | set select = NULL then all columns will be returned.
Navigate to a job
129 | 130 |job_open(jobname = NULL)133 | 134 |
| jobname | 139 |name of job to open |
140 |
|---|
The job_open() function opens a workbch job. The meaning of
146 | "open" here depends on context. If there is an RStudio project linked to the
147 | job and the RStudio API is available, then job_open() will switch the
148 | to the RStudio project that jobname is linked to. If this is not
149 | possible an there is a path associated with the job, then job_open()
150 | will change the working directory to that path. If neither option is possible
151 | then this function does nothing.
Note that when working interactively, job_open() can be called without
153 | specfying the jobname. In this case the user will be presented with
154 | prompts to select the desired job.
R/job_openurl.R
123 | job_openurl.RdNavigate to a URL associated with a job
129 | 130 |job_openurl(site, jobname = NULL)133 | 134 |
| site | 139 |label denoting the site (e.g., "github") |
140 |
|---|---|
| jobname | 143 |name of the job |
144 |
The job_openurl() function opens a URL associated with a
150 | job in a browser window. The site argument is the site nickname
151 | (e.g. "github", "homepage", etc) and the jobname argument specifies
152 | the job to use.
If no argument is specified job_openurl() will attempt to guess the
154 | current job by looking at any open RStudio projects. If no project is open
155 | or the RStudio API is not available it attempts to guess by looking at the
156 | working directory.
Scans for jobs
129 | 130 |job_seek(dirs = getOption("workbch.search"), seek = c("workbch", "git", 133 | "Rproj"), nesting = FALSE, owner = "", priority = 1, 134 | status = "active", tags = character(0))135 | 136 |
| dirs | 141 |directories to scan |
142 |
|---|---|
| seek | 145 |search criterion |
146 |
| nesting | 149 |allow nested jobs (default = FALSE) |
150 |
| owner | 153 |default owner for a created job |
154 |
| priority | 157 |default priority for a created job |
158 |
| status | 161 |default status for a created job |
162 |
| tags | 165 |default tags for a created job |
166 |
The job_seek() searches the folders listed in dirs
172 | to find possible candidates that could be added as workbch jobs, or to
173 | recover the location of any such jobs that may have moved. When candidate
174 | folders are found, the user is presented with prompts asking if they would
175 | like to add the folder as a workbch job (or pair it with an existing job
176 | if a match is discovered).
The search process uses a heuristic to discover possible jobs. A folder
178 | is considered a possible candidate if it has a .Rproj file, a
179 | .workbch file, or a git repository. If nesting = FALSE (the
180 | default), a directory that is contained within another directory that meets
181 | one of these criteria is not considered a candidate.
As much as possible the job_seek() function attempts to guess values
183 | for the various parameters. For instance, if there is a git repository that
184 | has an upstream remote (on gitbub, bitbucket or gitlab), it attempts to guess
185 | an appropriate URL for the remote. Similarly, if there is a .workbch
186 | sentinel file, it uses the contents of the file to try to match the folder
187 | against a known job and takes the jobname from the sentinel file. Otherwise
188 | it guesses a default value using the folder name.
189 | For parameter values that cannot be guessed from the folder itself, default
190 | values are specified using the owner, priority, status
191 | and tags arguments.
Regardless of the values guessed, the user is prompted either to confirm 193 | the guessed value (by hitting enter) or overriding the guess by supplying 194 | the value manually.
195 | 196 | 197 |