diff --git a/docs/use-cases/git-svn.md b/docs/extras/git-svn.md similarity index 100% rename from docs/use-cases/git-svn.md rename to docs/extras/git-svn.md diff --git a/docs/use-cases/self-contained-gitman.md b/docs/extras/self-contained-gitman.md similarity index 90% rename from docs/use-cases/self-contained-gitman.md rename to docs/extras/self-contained-gitman.md index f70ab9a0..b8e23a75 100644 --- a/docs/use-cases/self-contained-gitman.md +++ b/docs/extras/self-contained-gitman.md @@ -1,17 +1,16 @@ -# Self contained / Portable GitMan +# Self-contained / Portable GitMan There are scenarios where a global GitMan installation via [pip](https://github.com/pypa/pip) or a local GitMan installation via [poetry](https://github.com/sdispater/poetry) is not possible or difficult to manage. For example, when a local system doesn't have the required python or pip version installed and or the global installation may produce side effects (different parallel python versions on the same machine). -Furthermore there are scenarios where a high degree of reproducibility, managing multiple different versions of GitMan on the same machine and hassle free distribution of GitMan is desired. +Furthermore there are scenarios where a high degree of reproducibility, managing multiple different versions of GitMan on the same machine and hassle free distribution of GitMan is desired. In these scenarios, it can be helpful to use a self contained GitMan application besides the possibility to use a virtual environment (e.g. via pyenv + poetry or docker). -It is possible to build a single self contained OS-specific GitMan binary using [PyInstaller](https://www.pyinstaller.org/) that can be used locally or globally. +It is possible to build a single self contained OS-specific GitMan binary using [PyInstaller](https://www.pyinstaller.org/) that can be used locally or globally. Over this way it is possible to manage multiple different versions of GitMan on the same machine and to easily distribute the GitMan application (including all needed dependencies) by simply copying one single file. -Following this approach, the gitman.yml and the corresponding compatible version of the GitMan application can be managed side by side in the same repository to ensure +Following this approach, the gitman.yml and the corresponding compatible version of the GitMan application can be managed side by side in the same repository to ensure reproducibility and easy distribution. - ## Prerequisites ### General prerequisites @@ -20,26 +19,30 @@ The [PyInstaller](https://www.pyinstaller.org/) will encapsulate the required pa In this matter, ensure that the required python version and development tools are locally available (see [GitMan requirements](../index.md#Setup) and [development setup](../about/contributing.md#Setup)). -The compatible PyInstaller package will be automatically resolved by poetry. It is not necessary to explicitly install the PyInstaller via pip. +The compatible PyInstaller package will be automatically resolved by poetry. It is not necessary to explicitly install the PyInstaller via pip. Furthermore OS-specifc prerequisites are required. -Below there are some well-known prerequisites listed. +Below there are some well-known prerequisites listed. Depending on the local system it may need further steps to do. ### Linux-specific prerequisites - install the corresponding python developer package - - Debian based distros (e.g. Mint, Ubuntu, Xubuntu): + + - Debian based distros (e.g. Mint, Ubuntu, Xubuntu): + ```sh sudo apt-get install python-dev ``` + In cases where multiple python versions are installed it is may helpful to specify the concrete version of the python developer package like: + ```sh sudo apt-get install python3.7-dev ``` - - Fedora based distros (e.g. CentOS): + - Fedora based distros (e.g. CentOS): ```sh yum install python-devel ``` diff --git a/docs/setup/git-svn.md b/docs/setup/git-svn.md index 30205c31..22f9bf16 100644 --- a/docs/setup/git-svn.md +++ b/docs/setup/git-svn.md @@ -1,5 +1,7 @@ # Git SVN Setup +If you're planning to use `gitman` to manage Subversion repositories, ensure `git svn` is configured correctly. + ## Install missing SVN packages ```sh @@ -9,9 +11,7 @@ sudo apt-get install subversion libapache2-svn ## Credentials -In order for `gitman` to interact with `git svn`, it must be configured to store your SVN credentials (cached) for private repository access. - -To test, trying cloning one of your private repositories: +In order for `gitman` to interact with `git svn`, it must be configured to store your SVN credentials (cached) for private repository access. As a test, trying cloning one of your private repositories: ```sh $ git svn clone -r diff --git a/mkdocs.yml b/mkdocs.yml index c118863b..0805a39c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -25,9 +25,10 @@ nav: - Tracking Branches: use-cases/branch-tracking.md - Linking Feature Branches: use-cases/linked-features.md - Build System Integration: use-cases/build-integration.md - - Self contained GitMan: use-cases/self-contained-gitman.md - Sparse Checkouts: use-cases/sparse-checkouts.md - - Git SVN: use-cases/git-svn.md + - Extras: + - Git SVN Bridge: extras/git-svn.md + - Self-Contained GitMan: extras/self-contained-gitman.md - About: - Release Notes: about/changelog.md - Contributing: about/contributing.md