31 Bifurcar y clonar

Utilice bifurcar y clonar para obtener una copia del repositorio de otra persona si existe alguna posibilidad de que desee proponer un cambio al propietario, es decir, enviar una solicitud de cambio. Si está dudando entre “simplemente clonar” y “bifurcar y clonar”, opte por “bifurcar y clonar”.

Queremos lograr esto:

A continuación mostramos un par de métodos para bifurcar y clonar y debes elegir uno:

Utilice una combinación del navegador, la línea de comandos Git y RStudio
A través de usethis::create_from_github()

Vocabulario: DUEÑO/REPO se refiere a lo que llamamos el repositorio fuente, propiedad de DUEÑO, que no eres tú. TU/REPO se refiere a su bifurcación, es decir, su copia remota del repositorio fuente, en GitHub. Este es el mismo vocabulario utilizado en otros lugares, como el capítulo sobre configuraciones remotas comunes.

Este es un buen momento para navegar hasta el repositorio GitHub de interés, es decir, el repositorio fuente. DUEÑO/REPO.

31.1 Bifurcar y clonar sin usethis

Supongo que ya estás visitando el repositorio fuente en el navegador. En la esquina superior derecha, haz clic en Bifurcación.

Esto crea una copia de REPO en su cuenta de GitHub y lo lleva allí en el navegador. Ahora estamos mirando TU/REPO.

Clonar TU/REPO, que es tu copia del repositorio, también conocido como tu bifurcación, en tu máquina local. Asegúrese de clonar su repositorio, no el repositorio de origen. En otro lugar, describimos múltiples métodos para clonar un repositorio remoto. Elegir uno:

Las instrucciones de clonación en Proyecto existente, GitHub primero cubrir usethis y RStudio.
Las instrucciones de clonación en Conectarse a GitHub muestra cómo hacer esto con la línea de comando Git.

Tome una decisión consciente sobre el directorio de destino local y la URL HTTPS versus SSH.

31.1.1 Finaliza la configuración de bifurcación y clonación.

Si se detiene en este punto, tendrá lo que considero una configuración incompleta, descrita en otro lugar como “fork (salvable)”.

Sad fork where `upstream` is not configured.

Esto es triste, porque no existe una conexión directa entre su copia local del repositorio y el repositorio fuente TU/REPO.

Hay dos piezas de configuración más recomendadas:

Configure el repositorio de origen como upstream remoto
Configure su rama main local (o cualquiera que sea la predeterminada) para rastrear upstream/main, no origin/main

El apodo upstream técnicamente puede ser lo que quieras. Existe una fuerte tradición de utilizar upstream en este contexto y, aunque tengo mejores ideas, creo que es mejor conformarme. Cada libro, publicación de blog e hilo de Stack Overflow que lea utilizará upstream aquí. Guarda tu energía psíquica para otras cosas.

Estos pasos le facilitan mantenerse actualizado con los desarrollos en el repositorio de origen. Hablamos más a continuación sobre por qué nunca debes confirmar con la rama predeterminada, p. main, cuando estás trabajando en una bifurcación (ver Sección 31.4).

31.1.2 Configurar el control remoto `upstream`

El primer paso es obtener la URL del repositorio fuente DUEÑO/REPO. Navegue hasta el repositorio de origen en GitHub. Es fácil llegar desde su bifurcación, TU/REPO, a través del enlace “forked from” en la parte superior izquierda.

Utilice el gran botón verde “Code” para obtener la URL de DUEÑO/REPO en su portapapeles. Sea intencional al copiar la URL HTTPS o SSH.

Puede configurar el control remoto upstream con la línea de comando Git, usethis o RStudio.

A continuación se explica cómo utilizar la línea de comandos de Git en un shell:

git remote add upstream https://github.com/OWNER/REPO.git

usethis::use_git_remote() le permite configurar un control remoto Git. Ejecute esto en R:

usethis::use_git_remote(
  name = "upstream",
  url = "https://github.com/DUEÑO/REPO.git"
)

Finalmente, puedes hacer esto en RStudio, aunque parece un poco extraño. Haga clic en “New Branch” en el panel de Git (“dos cuadros morados y un cuadrado blanco”).

Esto revelará un botón para “Agregar control remoto”. Pinchalo. Ingrese upstream como nombre remoto y pegue la URL de DUEÑO/REPO que obtuvo de GitHub. Haga clic en “Agregar”. Rechace la oportunidad de agregar una nueva rama haciendo clic en “Cancelar”.

Independientemente de cómo haya configurado upstream, haga esto en un shell:

git fetch upstream

31.1.3 Configurar la rama de seguimiento ascendente para la rama predeterminada

Esto es opcional pero muy recomendable para la mayoría de situaciones de bifurcación y clonación. Vamos a configurar upstream/main desde el repositorio de origen como la rama de seguimiento ascendente del main local. (Si su sucursal predeterminada tiene un nombre diferente, sustitúyalo según corresponda.)

Esto es deseable para que un simple git pull importe cambios del repositorio fuente, no de su bifurcación. También significa que un simple git push (intentará) enviar al repositorio de origen, que casi siempre será rechazado ya que probablemente no tenga permiso. Esta falla le alertará del hecho de que está haciendo algo cuestionable, aunque aún será fácil echarse atrás.

Primero, obtenga información para el control remoto upstream. Esto es especialmente importante si acaba de configurar upstream por primera vez.

git fetch upstream

Los dos comandos siguientes hacen lo mismo; el primero es sólo una abreviatura del segundo. Haga esto con la línea de comando Git en un shell:

git branch -u upstream/main
git branch --set-upstream-to upstream/main

Si este flujo de trabajo de bifurcación y clonación le pareció largo y tedioso, ¡considere usar usethis::create_from_github() la próxima vez!

31.2 `usethis::create_from_github("OWNER/REPO", fork = TRUE)`

El paquete usethis tiene una función conveniente, create_from_github(), que puede hacer “bifurcación y clonación” (además de simplemente clonar). El argumento fork controla si el repositorio fuente está clonado o bifurcado y clonado. Tenga en cuenta que create_from_github(fork = TRUE) requiere que haya configurado un token de acceso personal de GitHub.

Supongo que ya estás visitando el repositorio fuente en el navegador. Ahora haga clic en el gran botón verde que dice “<> Código”. Copie una URL clonada a su portapapeles. Si sigue nuestro consejo predeterminado, copie la URL HTTPS. Pero si opta por SSH, asegúrese de copiar la URL de SSH.

Puede ejecutar el siguiente comando en cualquier sesión de R. Si usa RStudio, hágalo en la consola R de cualquier instancia de RStudio. En cualquier caso, después de completarlo exitosamente, deberías encontrarte en el nuevo proyecto que es el repositorio local conectado a tu bifurcación.

usethis::create_from_github(
  "https://github.com/DUEÑO/REPO",
  destdir = "~/ruta/a/dónde/quieres/el/local/repositorio/",
  fork = TRUE
)

El primer argumento es repo_spec y acepta la especificación del repositorio de GitHub en varias formas. En particular, puede utilizar la URL que acabamos de copiar para el repositorio fuente.

El argumento destdir especifica el directorio principal donde desea que resida la nueva carpeta (y el repositorio local de Git). Si no especifica destdir, use este valor predeterminado en algún lugar muy visible, como su escritorio. Si desea mantener los repositorios de Git en una determinada carpeta de su computadora, puede personalizar este valor predeterminado configurando la opción usethis.destdir en su .Rprofile.

El argumento fork especifica si se debe clonar (fork = FALSE) o bifurcar y clonar (fork = TRUE). A menudo no es necesario especificar “fork” y simplemente puedes disfrutar del comportamiento predeterminado, que se rige por tus permisos en el repositorio de origen. De forma predeterminada, fork = FALSE si puede enviar al repositorio de origen y fork = TRUE si no puede.

Así es como podría verse (tenga en cuenta que aceptamos el comportamiento predeterminado para muchos argumentos):

usethis::create_from_github("https://github.com/DUEÑO/REPO")
#> ℹ Defaulting to 'https' Git protocol
#> ✔ Setting `fork = TRUE`
#> ✔ Creating '/aluguna/rutal/al/local/REPO/'
#> ✔ Forking 'DUEÑO/REPO'
#> ✔ Cloning repo from 'https://github.com/TU/REPO.git' into '/alguna/ruta/al/local/REPO'
#> ✔ Setting active project to '/alguna/ruta/al/local/REPO'
#> ℹ Default branch is 'main'
#> ✔ Adding 'upstream' remote: 'https://github.com/DUEÑO/REPO.git'
#> ✔ Pulling changes from 'upstream/main'.
#> ✔ Setting remote tracking branch for local 'main' branch to 'upstream/main'
#> ✔ Setting active project to '<no active project>'

Para un usuario de RStudio, create_from_github(fork = TRUE) hace todo esto:

Bifurca el repositorio fuente en GitHub.
Clona tu bifurcación en un nuevo repositorio local (y en el Proyecto RStudio). Esto configura su bifurcación como el control remoto origin.
Configura el repositorio de origen como el repositorio remoto upstream.
Establece la rama de seguimiento ascendente para main (o cualquiera que sea la rama predeterminada) en upstream/main.
Abre una nueva instancia de RStudio en el nuevo repositorio local (y RStudio Project).

31.3 Interactúe con el nuevo repositorio

Si usaste usethis::create_from_github()o bifurcó y clonó a través de Proyecto existente, GitHub primero, probablemente esté en un proyecto RStudio para este nuevo repositorio.

De todos modos, únete a este proyecto, sea lo que sea que eso signifique para ti, utilizando tu método habitual.

Explore el nuevo repositorio de alguna manera adecuada. Si es un paquete, puede ejecutar las pruebas o verificarlo. Si se trata de un proyecto de análisis de datos, ejecute un script o renderice un Rmd. Convéncete de que has recibido el código.

Ahora debería estar en la posición perfecta para sincronizarse con los desarrollos en curso en el repositorio de origen y proponer nuevos cambios a través de una solicitud de cambios desde su bifurcación.

{fig-align=“center” fig-alt = “Fork and clone, ideal setup.” width=“60%”}

Puede utilizar los siguientes comandos para revisar más detalles esenciales de Git de su configuración de bifurcación y clonación:

Línea de comando Git en un shell:
- git remote -v
- git remote show origin (o upstream)
- git branch -vv
En R:
- usethis::git_remotes()
- usethis::git_sitrep()

En el shell, git remote -v debería revelar que sus controles remotos están configurados así:

origin    https://github.com/YOU/REPO.git (fetch)
origin    https://github.com/YOU/REPO.git (push)
upstream  https://github.com/OWNER/REPO.git (fetch)
upstream  https://github.com/OWNER/REPO.git (push)

Información comparable está disponible en R con usethis::git_remotes():

git_remotes()
#> $origin
#> [1] "https://github.com/YOU/REPO.git"
#> 
#> $upstream
#> [1] "https://github.com/OWNER/repo.git"

En el shell, con la rama predeterminada seleccionada, git branch -vv debería revelar que upstream/main es la rama de seguimiento ascendente:

~/some/repo/ % git branch -vv                   
* main 2739987 [upstream/main] Some commit message

Toda esta información sobre controles remotos y sucursales también se incluye en la rica información reportada con usethis::git_sitrep().

31.4 No te metas con `main`

Aquí hay algunos consejos finales sobre cómo trabajar en una situación de bifurcación y clonación.

Si realiza alguna confirmación en su repositorio local, recomiendo encarecidamente que trabaje en una nueva rama, no en main (o como se llame la rama predeterminada).

Le recomiendo enfáticamente que no realice confirmaciones con el main de un repositorio que haya bifurcado. Si se confirma main en un repositorio que no es de su propiedad, se crea una divergencia entre el historial de esa rama en el repositorio de origen y en su repositorio. De esto no surgirá más que dolor. (Si ya ha hecho esto, discutiremos cómo solucionar la situación en Um, ¿qué pasa si toco main?.)

Cuando tratas main como de solo lectura, hace la vida mucho más fácil cuando quieres importar upstream en tu copia. El DUEÑO de REPO también estará más feliz de recibir su solicitud de cambio de una rama que no sea main.

Para obtener más detalles, estas preguntas y respuestas sobre Stack Overflow son útiles: ¿Por qué es una mala práctica confirmar en la rama maestra de su bifurcación?.