es-es/about_DevDirManager.help.txt
|
TEMA
about_DevDirManager DESCRIPCIÓN CORTA DevDirManager es un módulo de PowerShell para gestionar y organizar directorios de desarrollo que contienen repositorios Git. Proporciona herramientas para escanear estructuras de directorios, mantener inventarios de repositorios y automatizar operaciones de clonación de repositorios. DESCRIPCIÓN LARGA El módulo DevDirManager ayuda a los desarrolladores a gestionar grandes colecciones de repositorios Git a través de múltiples estructuras de directorios. Ofrece funcionalidad para: * Escanear árboles de directorios para descubrir repositorios Git * Exportar inventarios de repositorios a múltiples formatos de archivo (CSV, JSON, XML) * Importar y restaurar colecciones de repositorios preservando diseños de carpetas * Sincronizar listas de repositorios con contenido real de directorios * Publicar inventarios de repositorios en GitHub Gists * Configurar comportamiento a través del sistema de configuración PSFramework El módulo utiliza un algoritmo de búsqueda en amplitud para escanear eficientemente grandes estructuras de directorios y soporta formatos de salida personalizados para datos de repositorios. SISTEMA DE CONFIGURACIÓN DevDirManager aprovecha el sistema de configuración PSFramework para proporcionar configuraciones flexibles y personalizables por el usuario. Los valores de configuración se pueden establecer usando el cmdlet Set-PSFConfig y persisten entre sesiones de PowerShell. Configuraciones disponibles: DevDirManager.Git.Executable Ruta al ejecutable git utilizado para operaciones de clonación. Valor predeterminado: git.exe Ejemplo: Set-PSFConfig -FullName 'DevDirManager.Git.Executable' -Value 'C:\Program Files\Git\cmd\git.exe' DevDirManager.Git.RemoteName Nombre remoto Git predeterminado para consultar al escanear repositorios. Valor predeterminado: origin Ejemplo: Set-PSFConfig -FullName 'DevDirManager.Git.RemoteName' -Value 'upstream' DevDirManager.DefaultOutputFormat Formato de archivo predeterminado para exportar/importar listas de repositorios. Valores válidos: CSV, JSON, XML Valor predeterminado: CSV Ejemplo: Set-PSFConfig -FullName 'DevDirManager.DefaultOutputFormat' -Value 'JSON' Para ver los valores de configuración actuales: Get-PSFConfig -Module DevDirManager Los valores de configuración son recuperados automáticamente por las funciones del módulo y no necesitan especificarse como parámetros a menos que desee anular los valores predeterminados configurados para una operación específica. FUNCIONES PRINCIPALES Descubrimiento de repositorios ------------------------------ Get-DevDirectory Escanea un árbol de directorios para descubrir todos los repositorios Git y recupera sus URLs remotas y configuración de usuario. Devuelve objetos DevDirManager.Repository con: - RootPath: Directorio base que fue escaneado - RelativePath: Ruta del repositorio relativa a RootPath - FullPath: Ruta absoluta al repositorio - RemoteName: Nombre del remoto Git (ej., 'origin') - RemoteUrl: URL del repositorio remoto - UserName: Configuración git user.name local del repositorio - UserEmail: Configuración git user.email local del repositorio - StatusDate: Fecha del commit más reciente o actividad del repositorio - IsRemoteAccessible: Booleano indicando si la URL remota es accesible (null si se usó -SkipRemoteCheck) Parámetros: - RootPath: Directorio a escanear para repositorios (predeterminado: ubicación actual) - SkipRemoteCheck: Omite la verificación de accesibilidad remota, mejorando el rendimiento pero sin marcar repositorios inaccesibles Gestión de listas de repositorios ---------------------------------- Export-DevDirectoryList Exporta una colección de objetos de repositorio a un archivo en formato CSV, JSON o XML. Detecta automáticamente el formato de la extensión de archivo o usa el formato predeterminado configurado. Import-DevDirectoryList Importa listas de repositorios desde archivos CSV, JSON o XML. Preserva la información de tipo DevDirManager.Repository para integración sin problemas con otras funciones del módulo. Operaciones de repositorio -------------------------- Restore-DevDirectory Clona repositorios desde un archivo de lista de repositorios, preservando la estructura de directorios original. Crea directorios padres necesarios y soporta clonación recursiva de submódulos. Si los metadatos del repositorio incluyen las propiedades UserName y UserEmail, estos valores se configuran en el repositorio clonado usando 'git config --local', asegurando que el repositorio clonado mantenga la misma identidad de usuario que el original. Parámetros: - DestinationPath: Directorio raíz donde se restaurarán los repositorios - Force: Sobrescribe directorios existentes eliminándolos antes de clonar - SkipExisting: Omite repositorios cuyo directorio de destino ya existe - ShowGitOutput: Muestra la salida de comandos git en lugar de suprimirla Sync-DevDirectoryList Realiza sincronización bidireccional entre una estructura de directorios y un archivo de lista de repositorios. Puede actualizar el archivo con nuevos repositorios encontrados en el directorio, o clonar repositorios faltantes desde el archivo. Al fusionar metadatos, los valores de repositorio locales para UserName, UserEmail y StatusDate se prefieren sobre los valores del archivo para garantizar precisión. Parámetros: - DirectoryPath: Directorio raíz que contiene repositorios Git - RepositoryListPath: Ruta al archivo de lista de repositorios - Force: Reenvía a Restore-DevDirectory para sobrescribir directorios existentes - SkipExisting: Reenvía a Restore-DevDirectory para omitir existentes - ShowGitOutput: Reenvía a Restore-DevDirectory para mostrar salida git - PassThru: Devuelve la lista de repositorios fusionada después de sincronización Integración GitHub ------------------ Publish-DevDirectoryList Publica una lista de repositorios en GitHub como Gist público o privado. Convierte automáticamente archivos CSV y XML a JSON para compatibilidad Gist. Requiere un token de acceso personal de GitHub con alcance gist. SOPORTE DE FORMATOS DE ARCHIVO DevDirManager soporta tres formatos de archivo para inventarios de repositorios: CSV (Valores separados por comas) - Formato tabular legible por humanos - Codificación UTF8 para soporte de caracteres internacionales - Ideal para visualización en aplicaciones de hoja de cálculo - La información de tipo se agrega durante la importación JSON (JavaScript Object Notation) - Formato de datos estructurado - Codificación UTF8 - Ideal para aplicaciones web y APIs - Serialización de profundidad 5 para propiedades anidadas - La información de tipo se agrega durante la importación XML (PowerShell CLIXML) - Formato de serialización nativo de PowerShell - Preserva automáticamente información de tipo - Ideal para intercambio de datos PowerShell-a-PowerShell - Maneja estructuras de objetos complejas Detección automática de formato Cuando no se especifica formato explícito, DevDirManager determina el formato usando esta precedencia: 1. Valor explícito del parámetro -Format 2. Extensión de archivo (.csv, .json, .xml) 3. Formato predeterminado configurado (DevDirManager.DefaultOutputFormat) 4. Error si no se puede determinar el formato Los parámetros de formato aceptan valores en mayúsculas y minúsculas (CSV, csv, Json, JSON, etc.) y se normalizan a mayúsculas internamente. TIPOS PERSONALIZADOS DevDirManager.Repository Representa un repositorio Git descubierto en un escaneo de directorio. Contiene: - RootPath [string]: Directorio base que fue escaneado - RelativePath [string]: Ruta relativa a RootPath - FullPath [string]: Ruta absoluta completa - RemoteName [string]: Nombre del remoto Git - RemoteUrl [string]: URL del repositorio remoto - UserName [string]: git user.name local del repositorio (desde .git/config) - UserEmail [string]: git user.email local del repositorio (desde .git/config) - StatusDate [datetime]: Fecha del commit más reciente o actividad del repositorio La vista de formato personalizada muestra: RelativePath, RemoteName, RemoteUrl, UserName, UserEmail, StatusDate Nota: UserName y UserEmail se extraen exclusivamente del archivo .git/config local del repositorio. Los valores de configuración git globales y del sistema se ignoran intencionalmente para garantizar seguimiento preciso de identidad por repositorio. DevDirManager.CloneResult Representa el resultado de una operación de clonación de repositorio. Contiene: - Status [string]: Success, Failed, o Skipped - TargetPath [string]: Ruta del directorio de destino - RemoteUrl [string]: URL del repositorio fuente DevDirManager.GistResult Representa un Gist de GitHub publicado. Contiene: - Description [string]: Descripción del Gist - Public [bool]: Gist público o privado - GistId [string]: Identificador único del Gist - HtmlUrl [string]: URL del navegador para el Gist EJEMPLOS Ejemplo 1: Descubrir repositorios en un directorio PS C:\> Get-DevDirectory -RootPath C:\Projects -Recurse Escanea C:\Projects recursivamente y devuelve todos los repositorios Git con sus URLs remotas. Ejemplo 2: Exportar lista de repositorios a CSV PS C:\> Get-DevDirectory -RootPath C:\Projects -Recurse | Export-DevDirectoryList -Path C:\Temp\repos.csv Exporta los repositorios descubiertos a un archivo CSV usando codificación UTF8. Ejemplo 3: Exportar a JSON con formato explícito PS C:\> Get-DevDirectory -RootPath C:\Projects -Recurse | Export-DevDirectoryList -Path C:\Temp\repos.txt -Format JSON Exporta a formato JSON aunque la extensión de archivo sea .txt. Ejemplo 4: Importar lista de repositorios y ver tipo PS C:\> $repos = Import-DevDirectoryList -Path C:\Temp\repos.csv PS C:\> $repos[0].PSObject.TypeNames Importa repositorios desde CSV y muestra la información de tipo. Ejemplo 5: Clonar repositorios desde una lista PS C:\> Restore-DevDirectory -RepositoryListPath C:\Temp\repos.csv -TargetDirectory D:\Projects Clona todos los repositorios del archivo CSV a D:\Projects, preservando la estructura de directorios original. Ejemplo 6: Sincronizar directorio con lista de repositorios PS C:\> Sync-DevDirectoryList -RepositoryListPath C:\Temp\repos.csv -Path C:\Projects -Recurse Compara C:\Projects con repos.csv y agrega nuevos repositorios al archivo. Ejemplo 7: Configurar formato predeterminado a JSON PS C:\> Set-PSFConfig -FullName 'DevDirManager.DefaultOutputFormat' -Value 'JSON' PS C:\> Get-DevDirectory -RootPath C:\Projects -Recurse | Export-DevDirectoryList -Path C:\Temp\repos Exporta a formato JSON porque no se proporciona extensión y el predeterminado es JSON. Ejemplo 8: Publicar lista de repositorios en GitHub Gist PS C:\> $token = Read-Host -AsSecureString -Prompt "GitHub Token" PS C:\> Publish-DevDirectoryList -FromPath C:\Temp\repos.csv -Description "My Repositories" -GitHubToken $token Publica la lista de repositorios como Gist público en GitHub. Ejemplo 9: Cambiar ruta del ejecutable Git PS C:\> Set-PSFConfig -FullName 'DevDirManager.Git.Executable' -Value 'C:\PortableGit\bin\git.exe' Configura DevDirManager para usar una instalación Git portable. Ejemplo 10: Escanear repositorios usando remoto diferente PS C:\> Set-PSFConfig -FullName 'DevDirManager.Git.RemoteName' -Value 'upstream' PS C:\> Get-DevDirectory -RootPath C:\Forks -Recurse Escanea repositorios y recupera la URL del remoto 'upstream' en lugar de 'origin'. Ejemplo 11: Ver configuración de usuario del repositorio PS C:\> Get-DevDirectory -RootPath C:\Projects | Select-Object RelativePath, UserName, UserEmail, StatusDate Muestra repositorios con su configuración de usuario local y fecha de actividad. UserName y UserEmail se extraen del archivo .git/config del repositorio (configuración local únicamente, config global/sistema se ignora). Ejemplo 12: Clonar repositorios con preservación de identidad de usuario PS C:\> Import-DevDirectoryList -Path C:\Temp\repos.csv | Restore-DevDirectory -DestinationPath D:\Projects Clona repositorios a D:\Projects. Si los metadatos del repositorio incluyen las propiedades UserName y UserEmail, estas se configuran automáticamente en cada repositorio clonado usando 'git config --local user.name' y 'git config --local user.email'. PATRONES DE FLUJO DE TRABAJO Patrones comunes de DevDirManager: Inventario y respaldo 1. Escanear sus directorios de desarrollo 2. Exportar a CSV/JSON para respaldo 3. Opcionalmente publicar en GitHub Gist para respaldo en la nube Restaurar entorno de desarrollo 1. Obtener lista de repositorios (desde respaldo o Gist) 2. Usar Restore-DevDirectory para clonar todos los repositorios 3. Mantiene estructura de carpetas original Mantener inventario actualizado 1. Usar Sync-DevDirectoryList periódicamente 2. Agrega automáticamente nuevos repositorios a su inventario 3. Opcionalmente clonar repositorios faltantes Sincronización multi-máquina 1. Exportar lista de repositorios desde máquina principal 2. Publicar en GitHub Gist 3. Descargar Gist en otras máquinas 4. Restaurar repositorios para replicar configuración DETALLES TÉCNICOS Algoritmo de búsqueda DevDirManager usa un algoritmo de búsqueda en amplitud (BFS) al escanear estructuras de directorios. Este enfoque: - Minimiza la profundidad de recursión para árboles de directorios grandes - Proporciona uso de memoria predecible - Maneja eficientemente jerarquías profundas - Omite directorios .git para evitar escanear internos del repositorio Codificación UTF8 Todas las operaciones de archivo usan codificación UTF8 para garantizar: - Soporte de caracteres internacionales - Compatibilidad multiplataforma - Comportamiento consistente en Windows, Linux y macOS Preservación de tipo Los objetos de repositorio mantienen su información de tipo a través de la serialización: - Formato XML: Automático vía Export-Clixml/Import-Clixml - Formato CSV: Tipo insertado durante Import-DevDirectoryList - Formato JSON: Tipo insertado durante Import-DevDirectoryList Vista de formato personalizada Los objetos DevDirManager.Repository tienen una vista de tabla personalizada que muestra: - RelativePath (para identificación fácil) - RemoteName (para mostrar qué remoto) - RemoteUrl (para verificación) - UserName (identidad de usuario local del repositorio) - UserEmail (email de usuario local del repositorio) - StatusDate (actividad más reciente) Otras propiedades están disponibles pero ocultas por defecto en vista de tabla. Seguimiento de identidad de usuario DevDirManager extrae y preserva la identidad de usuario local del repositorio: - UserName y UserEmail se leen solo de la sección [user] de .git/config - La configuración git global y del sistema se ignora intencionalmente - Al clonar repositorios, Restore-DevDirectory establece automáticamente user.name y user.email en el repositorio clonado si estos valores están presentes en los metadatos del repositorio - Esto garantiza que cada repositorio mantenga su identidad de commit prevista - Útil para gestionar repositorios con diferentes identidades de autor Fecha de actividad del repositorio La propiedad StatusDate representa la actividad más reciente del repositorio: - Extraída de la marca de tiempo del commit de la referencia HEAD actual - Lee .git/HEAD para determinar la referencia de rama actual - Usa el tiempo de modificación del archivo de referencia de rama como fecha de commit - Se recurre al tiempo de modificación de carpeta .git si HEAD no está disponible - Proporciona una forma simple de identificar repositorios recientemente activos SISTEMA DE REGISTRO DevDirManager usa el sistema de registro PSFramework para proporcionar información de diagnóstico completa. Todos los mensajes de registro soportan internacionalización, con localizaciones disponibles en inglés (en-us), francés (fr-fr) y español (es-es). Niveles de registro El módulo usa los niveles de registro de PSFramework para categorizar mensajes: - Debug: Información de diagnóstico detallada para solución de problemas - Verbose: Mensajes informativos sobre operaciones normales - System: Operaciones de configuración y nivel de sistema - Warning: Problemas no críticos que no detienen la ejecución - Error: Errores que pueden impedir completar operaciones Visualización de mensajes de registro Use parámetros comunes de PowerShell para controlar visibilidad de registros: - -Verbose: Muestra mensajes de nivel Verbose y superiores - -Debug: Muestra mensajes de nivel Debug y todos los demás niveles Ejemplo: PS C:\> Get-DevDirectory -RootPath C:\Projects -Verbose Características de registro PSFramework DevDirManager aprovecha las capacidades de registro avanzadas de PSFramework: - Creación automática de archivos de registro para diagnósticos persistentes - Registro estructurado con etiquetas para filtrado - Plantillas de mensajes para internacionalización consistente - Configuración en tiempo de ejecución de proveedores de registro Configurar proveedores de registro: PS C:\> Set-PSFLoggingProvider -Name logfile -FilePath C:\Logs\DevDirManager.log PS C:\> Set-PSFLoggingProvider -Name logfile -Enabled $true Ver mensajes registrados: PS C:\> Get-PSFMessage | Where-Object ModuleName -eq 'DevDirManager' Internacionalización Los mensajes de registro se localizan automáticamente según la cultura actual de PowerShell ($PSCulture). Idiomas soportados: - Inglés (en-us): Predeterminado - Francés (fr-fr): Français - Español (es-es): Español Anular cultura para pruebas: PS C:\> [System.Threading.Thread]::CurrentThread.CurrentUICulture = 'es-es' PS C:\> Get-DevDirectory -RootPath C:\Projects -Verbose Patrones de registro comunes Operaciones de escaneo de repositorio: - GetDevDirectory.ScanStart: Cuando comienza escaneo de directorio - GetDevDirectory.RepositoryFound: Cada vez que se descubre un repositorio - GetDevDirectory.ScanComplete: Resumen cuando termina escaneo Operaciones de importación/exportación: - ImportDevDirectoryList.Start: Comienza operación de importación - ExportDevDirectoryList.FormatResolved: Formato de archivo determinado - ImportDevDirectoryList.CompleteCSV/JSON/XML: Importación exitosa Operaciones de clonación/restauración: - RestoreDevDirectory.CloneFailed: Errores de git clone - RestoreDevDirectory.Complete: Resumen cuando termina restauración Operaciones de sincronización: - SyncDevDirectoryList.SyncStart: Comienza proceso de sincronización - SyncDevDirectoryList.RemoteUrlMismatch: Conflictos de URL detectados - SyncDevDirectoryList.Complete: Recuento final de repositorios Solución de problemas con registros Al encontrar problemas: 1. Reejecutar el comando con -Verbose para ver progreso detallado 2. Usar -Debug para máximo detalle de diagnóstico 3. Verificar registros PSFramework: Get-PSFMessage | Where-Object Level -eq Error 4. Revisar etiquetas de operación específicas para solución de problemas dirigida 5. Habilitar registro de archivos para registros de diagnóstico persistentes Ejemplo de flujo de trabajo de solución de problemas: PS C:\> Get-DevDirectory -RootPath C:\Projects -Verbose -Debug PS C:\> Get-PSFMessage | Where-Object Tag -contains "GetDevDirectory" PS C:\> Get-PSFMessage | Where-Object Level -eq Error | Format-List * PALABRAS CLAVE Git, Repositorio, DevOps, Control de código fuente, Gestión de directorios, Inventario, Respaldo, Restauración, Sincronización, GitHub, Gist, PSFramework, Configuración, Registro, Internacionalización VER TAMBIÉN Get-DevDirectory Export-DevDirectoryList Import-DevDirectoryList Restore-DevDirectory Sync-DevDirectoryList Publish-DevDirectoryList about_PSFramework_Configuration Get-PSFConfig Set-PSFConfig |