diff --git a/_bookdown.yml b/_bookdown.yml index 9d7fa0a7..a316d029 100644 --- a/_bookdown.yml +++ b/_bookdown.yml @@ -42,7 +42,7 @@ rmd_files: [ "remote-setups-intro.Rmd", "remote-setups-common.Rmd", - "remote-setups-peculiar.Rmd", + "remote-setups-equivocal.Rmd", "workflows-intro.Rmd", "workflows-repeated-amend.Rmd", diff --git a/connect-credential-caching.Rmd b/connect-credential-caching.Rmd index 4f475395..29a8d2af 100644 --- a/connect-credential-caching.Rmd +++ b/connect-credential-caching.Rmd @@ -14,7 +14,7 @@ Remember: the transport protocol is controlled by the URL you use for remote rep HTTPS remotes look like `https://github.com//.git`. SSH remotes look like `git@github.com:/.git`. -## You should get a personal access token (PAT) +## You should get a personal access token (PAT) {#get-a-pat} ### Why a PAT? diff --git a/img/maybe_fork.png b/img/maybe_fork.png new file mode 100644 index 00000000..786ed4f5 Binary files /dev/null and b/img/maybe_fork.png differ diff --git a/img/maybe_ours_or_theirs.png b/img/maybe_ours_or_theirs.png new file mode 100644 index 00000000..d73ead73 Binary files /dev/null and b/img/maybe_ours_or_theirs.png differ diff --git a/process-github-config-diagrams-for-happy-git.R b/process-github-config-diagrams-for-happy-git.R index 3be912cc..4607b82f 100644 --- a/process-github-config-diagrams-for-happy-git.R +++ b/process-github-config-diagrams-for-happy-git.R @@ -5,12 +5,12 @@ library(here) # TODO: soon, I should move the source Keynote document (or part of it) # into this project -img_paths <- dir_ls("~/rrr/happy-git-with-r-slides/github-configs/2020-06_usethis-motivated-git-diagrams/") +exported_paths <- dir_ls("~/rrr/happy-git-with-r-slides/github-configs/2020-06_usethis-motivated-git-diagrams/") -path_file(img_paths) +path_file(exported_paths) # practicing -y <- image_read(img_paths[[2]]) +y <- image_read(exported_paths[[2]]) y # wow much fiddling here to get the crop geometry right @@ -20,7 +20,11 @@ z %>% image_border(color = "blue") # doing it to all figs -dir_create(here("img", "github-configs")) +dir <- here("img", "github-configs") +dir_create(dir) +# clean out previous attempts +dir_ls(dir) %>% + file_delete() f <- function(file) { file %>% @@ -29,16 +33,14 @@ f <- function(file) { image_write(here("img", "github-configs", path_file(file))) } -walk(img_paths, f) +walk(exported_paths, f) -cropped_paths <- dir_ls(here("img", "github-configs")) +cropped_paths <- dir_ls(dir) -path_file(img_paths) +path_file(cropped_paths) -name_dat <- tibble( - raw = path_file(img_paths) -) %>% - mutate(number = str_extract(raw, "\\d+(?=[.]jpeg$)")) +name_dat <- tibble(filename = path_file(cropped_paths)) %>% + mutate(number = str_extract(filename, "\\d+(?=[.]jpeg$)")) usethis_labels <- tribble( ~ number, ~ label, @@ -49,7 +51,9 @@ usethis_labels <- tribble( "005", "fork-them", "006", "fork-them-pull-request", "007", "fork-ours", - "008", "fork_upstream_is_not_origin_parent" + "008", "fork_upstream_is_not_origin_parent", + "009", "maybe_ours_or_theirs", + "010", "maybe_fork" ) name_dat <- name_dat %>% @@ -57,5 +61,6 @@ name_dat <- name_dat %>% file_copy( cropped_paths, - here("img", path_ext_set(name_dat$label, "png")) + here("img", path_ext_set(name_dat$label, "png")), + overwrite = TRUE ) diff --git a/remote-setups-common.Rmd b/remote-setups-common.Rmd index be2d0e68..9c5bca21 100644 --- a/remote-setups-common.Rmd +++ b/remote-setups-common.Rmd @@ -21,7 +21,7 @@ This is not very exciting, but sets the stage for what's to come. We introduce t `usethis::use_git()` can create this setup in a local project, i.e. it initializes a Git repo. usethis describes this setup as "no_github". -## Ours (more specifically, mine) +## Ours (more specifically, mine) {#ours-you} A common next step is to associate a local repo with a copy on GitHub, owned by you. @@ -33,7 +33,7 @@ A remote named `origin` is configured and you have permission to push to (and pu `usethis::use_github()` can create this setup from a local repository, as long as you have configured a GitHub personal access token. usethis describes this setup as "ours". -## Ours +## Ours {#ours-them} Here is a variation on "ours" that is equivalent in practice. @@ -55,7 +55,7 @@ Way to get here with usethis: usethis describes this setup as "ours". -## Theirs +## Theirs {#theirs} This is a setup that many people get themselves into, when it's not actually what they need. It's not broken *per se*, but it's limiting. @@ -76,7 +76,7 @@ usethis describes this setup as "theirs". What if you do want to make a pull request? This means you should have done *fork-and-clone* instead of *clone*. If you've made no changes or they're easy to save somewhere temporarily, just start over with a fork-and-clone workflow (see below) and re-introduce your changes. It is also possible to preserve your work in a local branch, fork the primary repo, re-configure your remotes, re-sync up with the source repo, and get back on track. But this is much easier to goof up. And remember to use `usethis::create_from_github(fork = TRUE)` in the future! -## Fork (of theirs) +## Fork (of theirs) {#fork-them} This is an ideal setup if you want to make a pull request and generally follow the development of a source repo owned by someone else. @@ -102,7 +102,7 @@ In this case, you have permission to push to the source repo, but you elect to c `usethis::create_from_github("OWNER/REPO", fork = TRUE)` can create this setup, as long as you have configured a GitHub personal access token (PAT). usethis describes this setup as "fork". -## Fork (salvageable) +## Fork (salvageable) {#fork_upstream_is_not_origin_parent} Here is one last fork setup that's sub-optimal, but it can be salvaged. diff --git a/remote-setups-equivocal.Rmd b/remote-setups-equivocal.Rmd new file mode 100644 index 00000000..47da3d9d --- /dev/null +++ b/remote-setups-equivocal.Rmd @@ -0,0 +1,51 @@ +# Equivocal remote setups {#equivocal} + +Just like the previous section about the most common setups, we only consider a very constrained set of remotes: + +* The remote is on GitHub, e.g. its URL looks something like `https://github.com/OWNER/REPO.git` or `git@github.com:OWNER/REPO.git`. +* The remote is named `origin` or `upstream`. + +The setups described here are characterized by *incomplete information*. +This section exists mostly to explain feedback that the usethis package might give about a GitHub remote configuration. *2020-10 note: this currently refers to features in a development version of usethis. These features will appear in usethis v2.0.0.* + +To identify any of the remote setups described in section \@ref(common-remote-setups), we need information from GitHub: + + * Whether you can push to a repo + * Whether a repo is a fork + * For a fork, what is its source repo + +Sometimes some of this information is publicly available, but some of it never is, such as repo permissions. +This means that programmatic access to this information, i.e. requests to the GitHub API, generally requires authorization by an authenticated GitHub user. + +This means that client packages, like usethis, work best when you have configured a GitHub personal access token (PAT). +See section \@ref(get-a-pat) for more details on why and how to do that. + +(If you've configured a PAT and are being told your GitHub config is problematic, consider these other explanations: Are you offline? Is GitHub down?) + +## Maybe "ours" or "theirs" + +When we detect just one GitHub remote, but we can't verify the info above, usethis describes the setup as "maybe_ours_or_theirs". + +```{r maybe_ours_or_theirs, echo = FALSE, out.width = "60%"} +knitr::include_graphics("img/maybe_ours_or_theirs.png") +``` + +Once a PAT is available, this setup can be identified as being ["ours" (belonging to you)](#ours-you), ["ours" (but belonging to someone else)](#ours-them), or ["theirs"](#theirs). + +## Maybe fork + +When we detect just two GitHub remotes, but we can't verify the info above, usethis describes the setup as "maybe_fork". + +```{r maybe_fork, echo = FALSE, out.width = "60%"} +knitr::include_graphics("img/maybe_fork.png") +``` + +Once a PAT is available, this setup can be identified as being a well-configured [fork](#fork-them) or a [fork with incomplete setup](#fork_upstream_is_not_origin_parent) (or possibly something more weird). + +## How to fix + +These setups aren't necessarily broken, but usethis needs more information to operate. + +To "fix" this, set up a GitHub personal access token. +See section \@ref(get-a-pat) for more details on why and how to do that. + diff --git a/remote-setups-peculiar.Rmd b/remote-setups-peculiar.Rmd deleted file mode 100644 index 76608866..00000000 --- a/remote-setups-peculiar.Rmd +++ /dev/null @@ -1,10 +0,0 @@ -# Peculiar remote setups {#unsupported} - -Just like the previous section about the most common setups, we only consider a very constrained set of remotes: - -* The remote is on GitHub. -* The remote is named `origin` or `upstream`. - -This section exists as counterpoint to the previous. Here we provide more details on remote setups that are more unusual and, usually, not very functional. In general, these are setups usethis cannot work with. We try to suggest a better alterntive in each case. *2020-06 note: this currently refers to features in a development version of usethis. These features are not in v1.6.1 = the current CRAN version.* - -*section coming soon*