Configuración de un repositorio local de Git para documentación

Artigo
12/20/2023

En este artículo se detallan los pasos para configurar un repositorio de Git en el equipo local, con la intención de contribuir a la documentación de Microsoft. Los colaboradores pueden usar un repositorio clonado localmente para agregar nuevos artículos, realizar ediciones importantes en los artículos existentes o cambiar las ilustraciones.

Ejecute estas actividades de configuración por única vez para comenzar a contribuir:

Determine el repositorio adecuado.
Bifurque el repositorio de GitHub a su cuenta de GitHub.
Elija una carpeta local para los archivos clonados.
Clone el repositorio en la máquina local.
Configure el valor remoto ascendente.

Importante

Si solo va a realizar cambios de menor importancia, no necesita realizar los pasos de este artículo. Consulte Edición en el explorador para obtener información sobre cómo realizar modificaciones rápidas sin instalar ninguna herramienta.

Información general

Para contribuir a la documentación de Microsoft Learn, puede crear y editar archivos de Markdown localmente clonando el repositorio de documentación correspondiente. Microsoft requiere que bifurque el repositorio adecuado en su cuenta de GitHub de forma que tenga permisos de lectura y escritura para almacenar los cambios propuestos. A continuación, use las solicitudes de incorporación de cambios para combinar los cambios en el repositorio central compartido de solo lectura.

Captura de pantalla que muestra el flujo de trabajo de GitHub para obtener información que fluye entre el clon ascendente, de origen y local.

Determinar el repositorio

La documentación hospedada en Microsoft Learn reside en varios repositorios diferentes de GitHub.

Si no está seguro de en qué repositorio reside un artículo, visite el artículo desde el explorador web. Seleccione el vínculo Editar (icono de lápiz) de la esquina superior derecha del artículo.
Esta acción le lleva al archivo de origen en GitHub. El nombre del repositorio se muestra en la esquina superior izquierda de la página.

Por ejemplo, estos repositorios populares están disponibles para realizar contribuciones públicas:
- Contenido de la comunidad de Microsoft Learn https://github.com/MicrosoftDocs/community-content/
- Documentación de Azure https://github.com/MicrosoftDocs/azure-docs
- Documentación de SQL Server https://github.com/MicrosoftDocs/sql-docs
- Documentación de Visual Studio https://github.com/MicrosoftDocs/visualstudio-docs
- Documentación de .NET https://github.com/dotnet/docs
- Documentación de Azure SDK para .NET https://github.com/azure/azure-docs-sdk-dotnet
- Documentación de ConfigMgr https://github.com/MicrosoftDocs/SCCMdocs

Bifurcar el repositorio

Una vez que haya identificado el repositorio correcto, el siguiente paso es bifurcar el repositorio en su propia cuenta de GitHub.

La bifurcación de un repositorio crea una copia de este en su cuenta de GitHub. Es necesario usar una bifurcación personal, porque todos los repositorios de documentación de Microsoft proporcionan acceso de solo lectura, pero la bifurcación proporciona acceso de escritura para realizar los cambios. La bifurcación permite abrir solicitudes de incorporación de cambios en el repositorio de Microsoft.

Desde la página del repositorio principal de GitHub, seleccione el botón Bifurcar en la parte superior derecha.
En la pantalla Crear una nueva bifurcación, asegúrese de que Propietario esté establecido en su nombre de usuario y de que esté activada la opción Copiar solo la rama principal. Opcionalmente, cambie los campos Nombre del repositorio y Descripción.

Clonación del repositorio

Clonar significa crear una copia de un repositorio en el equipo local.

Advertencia

NO clone repositorios locales en carpetas sincronizadas con OneDrive. Al elegir la carpeta en la que clonará el repositorio, evite las carpetas que se sincronicen con OneDrive (por ejemplo, la carpeta Documentos). OneDrive puede provocar conflictos de combinación no deseados al volver a combinar los cambios en la rama principal. Lo mejor es crear una ruta de archivo corta en la unidad C:\ (por ejemplo, C:\GitHub).
Git en Windows: habilite los nombres de ruta de acceso larga. De forma predeterminada, Git para Windows deshabilita la compatibilidad con rutas de archivo largas, lo que impide que se clone cualquier archivo con una ruta de acceso de destino de más de 255 caracteres. Habilite las rutas de archivo largas para evitar este problema mediante la ejecución del siguiente comando como administrador:
git config --global core.longpaths true

Cree una carpeta denominada GitHub en el equipo local. Por ejemplo, C:\GitHub. (No realice la clonación en una carpeta sincronizada de OneDrive).
En un explorador, vaya a GitHub.com e inicie sesión.
En GitHub, en la parte superior derecha, en la lista desplegable del perfil, seleccione Sus repositorios. Aparece la página de repositorios con una lista de los repositorios bifurcados.
Seleccione el repositorio que quiera clonar. Aparece la página de repositorios de su bifurcación.

Asegúrese de que está en la página del repositorio de su bifurcación, no de la página del repositorio de producción. Puede confirmar que el repositorio en el que está es la bifurcación comprobando la dirección URL: debe mostrar el nombre de usuario de GitHub, no la organización de Microsoft (por ejemplo, https://github.com/nancydavolio/azure-docs y NO https://github.com/MicrosoftDocs/azure-docs). Además, verá su nombre en la esquina superior izquierda y verá una nota que indica bifurcación de seguido del nombre del repositorio principal.
Seleccione la pestaña Código de <> en la parte superior izquierda de la página.
En el lado derecho, en la lista desplegable Código , copie la dirección URL en la opción HTTPS.

Importante

Ha copiado la dirección URL de clonación a través de la interfaz de usuario de GitHub. El resto de los pasos se deben realizar en el terminal de VS Code.

Para clonar desde Visual Studio Code

Abra Visual Studio Code.
En el menú de navegación superior, seleccione Ver y luego seleccione Terminal. La vista de terminal aparece en la parte inferior de la pantalla de Visual Studio Code.
En la vista Terminal, ejecute el comando para cambiar el directorio (cd) a la carpeta GitHub que creó para los repositorios en la unidad en el paso 1 de la sección Clonación de un repositorio.

Ejemplo:
```
 cd C:\GitHub
```
Si recibe un error, es posible que tenga que cambiar el directorio carpeta a carpeta.

Ejecute el comando siguiente para clonar el repositorio:

git clone <paste the clone URL you copied via the GitHub UI>

Por ejemplo:

git clone https://github.com/nancydavolio/azure-docs.git

Cuando se le pida que se autentique a través del explorador, elija el botón "Iniciar sesión con el explorador" y complete el proceso. Asegúrese de descargar la versión más reciente de Git, que admite la autenticación a través de la funcionalidad del explorador. Si decide usar un token de acceso personal de GitHub, puede generar una de estas instrucciones: Crear un tokende acceso personal.

El comando de clonación descarga los archivos del repositorio desde su bifurcación a una carpeta nueva ubicada en el lugar que haya elegido en el paso 3. Dentro de la carpeta actual, se crea una carpeta nueva. En función del tamaño del repositorio, la operación puede tardar varios minutos. Una vez creada la carpeta, puede explorarla para ver su estructura.

Configuración de repositorios remotos

Tras clonar el repositorio, configure una conexión remota de solo lectura al repositorio principal llamada upstream (ascendente). Los repositorios remotos son alias que hacen referencia a repositorios remotos. Origen hace referencia a la bifurcación y ascendente hace referencia al repositorio de producción. Git crea automáticamente el repositorio remoto origin cuando ejecuta el comando clone. Esta URL ascendente se utiliza para mantener el repositorio local sincronizado con los últimos cambios que realicen otros usuarios.

Ejecute los comandos siguientes en Git Bash o en el terminal de VS Code.

Cambie el directorio (cd) a la carpeta del repositorio que se creó con el comando clone. Por ejemplo:
```
cd repo-name
```
Ejecute el comando siguiente para agregar un repositorio remoto denominado upstream que apunte al repositorio de producción. Por ejemplo, la dirección URL del repositorio upstream es https://github.com/MicrosoftDocs/azure-docs.git en lugar de https://github.com/nancydavolio/azure-docs.git.
```
git remote add upstream <the clone URL of the main repo>
```
Por ejemplo:
```
git remote add upstream https://github.com/MicrosoftDocs/azure-docs.git
```

Ejecute el siguiente comando para asegurarse de que los repositorios remotos sean correctos:

git remote -v

Ejemplo de salida:

origin  https://github.com/nancydavolio/azure-docs.git (fetch)
origin  https://github.com/nancydavolio/azure-docs.git (push)
upstream        https://github.com/MicrosoftDocs/azure-docs.git (fetch)
upstream        https://github.com/MicrosoftDocs/azure-docs.git (push)

Si ha cometido algún error, quite el repositorio remoto y repita el paso para volver a agregarlo. Para quitar upstream, ejecute el comando.
```
git remote remove upstream
```

Pasos siguientes

Ahora que ha configurado el clon local, es el momento de realizar cambios importantes.

Compartir por