SVNBOOK Chap3 Sparse Directories

De Framalang Wiki.

Cette section fait partie du livre Version control with subversion

Pseudo	Code	Rôle	Statut
Hotshot92		Traduction	fait
	SVF	1ère Relecture	Fait
		Validation

Source : http://svnbook.red-bean.com/en/1.5/svn-book.html#svn.advanced.sparsedirs

Sommaire

1 Sparse Directories

Sparse Directories

Répertoires clairsemés

By default, most Subversion operations on directories act in a recursive manner. For example, svn checkout creates a working copy with every file and directory in the specified area of the repository, descending recursively through the repository tree until the entire structure is copied to your local disk. Subversion 1.5 introduces a feature called sparse directories (or shallow checkouts) that allows you to easily check out a working copy—or a portion of a working copy—more shallowly than full recursion, with the freedom to bring in previously ignored files and subdirectories at a later time.

Par défaut, la plupart des opérations Subversion sur des répertoires agissent de manière récursive. Par exemple, svn checkout crée une copie de travail avec tous les fichiers et répertoires de la zone spécifiée du dépôt, en descendant récursivement dans l'arborescence du dépôt pour en copier la structure complète sur votre disque local. Subversion 1.5 introduit une nouvelle fonctionnalité appelée 'répertoires clairsemés' (ou extractions superficielles) qui permet d'obtenir facilement une copie de travail (ou une simple portion d'une copie de travail) moins profonde que via la récursion complète, avec la possibilité de n'extraire que plus tard les répertoires et les fichiers ignorés auparavant.

Paragraphe 2

For example, say we have a repository with a tree of files and directories with names of the members of a human family with pets. (It's an odd example, to be sure, but bear with us.) A regular svn checkout operation will give us a working copy of the whole tree:

$ svn checkout file:///var/svn/repos mom
A    mom/son
A    mom/son/grandson
A    mom/daughter
A    mom/daughter/granddaughter1
A    mom/daughter/granddaughter1/bunny1.txt
A    mom/daughter/granddaughter1/bunny2.txt
A    mom/daughter/granddaughter2
A    mom/daughter/fishie.txt
A    mom/kitty1.txt
A    mom/doggie1.txt
Checked out revision 1.
$

Par exemple, imaginons un dépôt dont l'arborescence des fichiers et répertoires est constituée des noms des membres d'une famille et de leurs animaux de compagnie (c'est assurément un exemple bizarre, mais soit). Un svn checkout standard nous donnerait une copie de travail de l'ensemble de l'arborescence :

$ svn checkout file:///var/svn/depot maman
A    maman/fils
A    maman/fils/petit-fils
A    maman/fille
A    maman/fille/petite-fille1
A    maman/fille/petite-fille1/lapinou1.txt
A    maman/fille/petite-fille1/lapinou2.txt
A    maman/fille/petite-fille2
A    maman/fille/poissonou.txt
A    maman/minou1.txt
A    maman/toutou1.txt
Révision 1 extraite.
$

Paragraphe 3

Now, let's check out the same tree again, but this time we'll ask Subversion to give us only the topmost directory with none of its children at all:

$ svn checkout file:///var/svn/repos mom-empty --depth empty
Checked out revision 1.
$

Maintenant, extrayons la même arborescence, mais cette fois en demandant à Subversion de nous donner uniquement le répertoire racine sans les enfants :

$ svn checkout file:///var/svn/depot maman-vide --depth empty
Révision 1 extraite.
$

Paragraphe 4

Notice that we added to our original svn checkout command line a new --depth option. This option is present on many of Subversion's subcommands and is similar to the --non-recursive (-N) and --recursive (-R) options. In fact, it combines, improves upon, supercedes, and ultimately obsoletes these two older options. For starters, it expands the supported degrees of depth specification available to users, adding some previously unsupported (or inconsistently supported) depths. Here are the depth values that you can request for a given Subversion operation:

--depth empty: Include only the immediate target of the operation, not any of its file or directory children.
--depth files: Include the immediate target of the operation and any of its immediate file children.
--depth immediates: Include the immediate target of the operation and any of its immediate file or directory children. The directory children will themselves be empty.
--depth infinity: Include the immediate target, its file and directory children, its children's children, and so on to full recursion.

Remarquez que nous avons ajouté l'option --depth à la commande svn checkout originale. Cette option existe pour de nombreuses sous-commandes Subversion et est similaire aux options --non-recursive (-N) et --recursive (-R). En fait, elle combine, améliore, remplace et à terme rend obsolète ces deux options plus anciennes. Déjà, elle permet à l'utilisateur de spécifier le niveau de récursion de façon plus précise, en ajoutant des niveaux auparavant non supportés (ou de manière peu satisfaisante). Voici les valeurs de niveau de récursion que vous pouvez ajouter à vos requêtes Subversion :

--depth empty: Inclut uniquement la cible immédiate de l'opération, sans aucun fichier ou répertoire fils.
--depth files: Inclut la cible immédiate de l'opération et tous les fichiers fils immédiats.
--depth immediates: Inclut la cible immédiate de l'opération et tous ses sous-répertoires et fils immédiats. Les répertoires fils seront eux-mêmes vides.
--depth infinity: Inclut la cible immédiate, les fichiers et répertoires fils, les fils des fils, et ainsi de suite pour réaliser une récursion complète.

Paragraphe 5

Of course, merely combining two existing options into one hardly constitutes a new feature worthy of a whole section in our book. Fortunately, there is more to this story. This idea of depth extends not just to the operations you perform with your Subversion client, but also as a description of a working copy citizen's ambient depth, which is the depth persistently recorded by the working copy for that item. Its key strength is this very persistence—the fact that it is sticky. The working copy remembers the depth you've selected for each item in it until you later change that depth selection; by default, Subversion commands operate on the working copy citizens present, regardless of their selected depth settings.

Bien sûr, la simple combinaison de deux options existantes en une seule ne constitue pas une nouvelle fonctionnalité méritant une section complète de ce livre. Heureusement, il y a plus à en dire. Ce concept de profondeur ne s'applique pas uniquement aux opérations réalisées avec le client Subversion mais il s'étend aussi à la description de la copie de travail elle-même, en tant que niveau associé de manière permanente par la copie de travail à chaque élément. La force de ce concept est cette permanence. La copie de travail se rappelle le niveau de récursion que vous avez choisi pour chaque élément qui la compose, jusqu'à ce que vous en changiez. Par défaut, les commandes Subversion agissent sur les éléments présents dans la copie de travail, indépendamment de leur niveau de récursion propre.

TIP

You can check the recorded ambient depth of a working copy using the svn info command. If the ambient depth is anything other than infinite recursion, svn info will display a line describing that depth value:

$ svn info mom-immediates | grep '^Depth:' 
Depth: immediates
$

Vous pouvez vérifier le niveau de récursion d'une copie de travail en utilisant la commande svn info. Si le niveau de récursion n'est pas infini, svn info affichera une ligne indiquant le niveau de récursion :

$ svn info maman-immediats | grep '^Profondeur :' 
Profondeur : immédiates
$

Paragraphe 7

Our previous examples demonstrated checkouts of infinite depth (the default for svn checkout) and empty depth. Let's look now at examples of the other depth values:

$ svn checkout file:///var/svn/repos mom-files --depth files
A    mom-files/kitty1.txt
A    mom-files/doggie1.txt
Checked out revision 1.
$ svn checkout file:///var/svn/repos mom-immediates --depth immediates
A    mom-immediates/son
A    mom-immediates/daughter
A    mom-immediates/kitty1.txt
A    mom-immediates/doggie1.txt
Checked out revision 1.
$

Ces premiers exemples comportaient des extractions avec un niveau infini de récursion (la valeur par défaut de svn checkout) ou avec un niveau nul. Voyons maintenant des exemples avec d'autres valeurs de niveau de récursion :

$ svn checkout file:///var/svn/depot maman-fichiers --depth files
A    maman-fichiers/minou1.txt
A    maman-fichiers/toutou1.txt
Révision 1 extraite.
$ svn checkout file:///var/svn/depot maman-immediats --depth immediates
A    maman-immediats/fils
A    maman-immediats/fille
A    maman-immediats/minou1.txt
A    maman-immediats/toutou1.txt
Révision 1 extraite.
$

Paragraphe 8

As described, each of these depths is something more than only the target, but something less than full recursion.

We've used svn checkout as an example here, but you'll find the --depth option present on many other Subversion commands, too. In those other commands, depth specification is a way to limit the scope of an operation to some depth, much like the way the older --non-recursive (-N) and --recursive (-R) options behave. This means that when operating on a working copy of some depth, while requesting an operation of a shallower depth, the operation is limited to that shallower depth. In fact, we can make an even more general statement: given a working copy of any arbitrary—even mixed—ambient depth, and a Subversion command with some requested operational depth, the command will maintain the ambient depth of the working copy members while still limiting the scope of the operation to the requested (or default) operational depth.

Comme indiqué, chacun de ces deux niveaux se situe quelque part entre la cible toute simple et la récursion complète.

Nous avons utilisé la commande svn checkout pour nos exemples, mais l'option --depth est également accessible depuis beaucoup d'autres commandes Subversion. Pour ces autres commandes, spécifier un niveau de récursion est une manière de limiter le rayon d'action d'une opération à un niveau, à l'instar des vieilles options --non-recursive (-N) et --recursive (-R). Cela veut dire que lorsque vous travaillez sur un copie de travail d'un certain niveau et que vous faites une opération sur un niveau plus faible, l'opération est limitée à ce niveau faible. En fait, on peut généraliser ce raisonnement : pour une copie de travail d'un niveau de récursion arbitraire (éventuellement hétérogène) et pour une commande Subversion comportant un niveau de récursion, la commande conservera le niveau de récursion associé aux éléments de la copie de travail tout en limitant le rayon d'action de l'opération au niveau demandé (ou celui par défaut).

Paragraphe 9

In addition to the --depth option, the svn update and svn switch subcommands also accept a second depth-related option: --set-depth. It is with this option that you can change the sticky depth of a working copy item. Watch what happens as we take our empty-depth checkout and gradually telescope it deeper using svn update --set-depth NEW-DEPTH TARGET:

$ svn update --set-depth files mom-empty
A    mom-empty/kittie1.txt
A    mom-empty/doggie1.txt
Updated to revision 1.
$ svn update --set-depth immediates mom-empty
A    mom-empty/son
A    mom-empty/daughter
Updated to revision 1.
$ svn update --set-depth infinity mom-empty
A    mom-empty/son/grandson
A    mom-empty/daughter/granddaughter1
A    mom-empty/daughter/granddaughter1/bunny1.txt
A    mom-empty/daughter/granddaughter1/bunny2.txt
A    mom-empty/daughter/granddaughter2
A    mom-empty/daughter/fishie1.txt
Updated to revision 1.
$

En plus de l'option --depth, les sous-commandes svn update et svn switch acceptent une deuxième option relative au niveau de récursion : --set-depth. C'est cette option qui vous permet de changer le niveau de récursion associé à un élément d'une copie de travail. Regardez ce qui se passe après avoir extrait notre niveau zéro puis graduellement augmenté le niveau de récursion en utilisant la commande svn update --set-depth NOUVEAU_NIVEAU CIBLE :

$ svn update --set-depth files maman-vide
A    maman-vide/minou1.txt
A    maman-vide/toutou1.txt
Actualisé à la révision 1.
$ svn update --set-depth immediates maman-vide
A    maman-vide/fils
A    maman-vide/fille
Actualisé à la révision 1.
$ svn update --set-depth infinity maman-vide
A    maman-vide/fils/petit-fils
A    maman-vide/fille/petite-fille1
A    maman-vide/fille/petite-fille1/lapinou1.txt
A    maman-vide/fille/petite-fille1/lapinou2.txt
A    maman-vide/fille/petite-fille2
A    maman-vide/fille/poissonou1.txt
Actualisé à la révision 1.
$

Paragraphe 10

As we gradually increased our depth selection, the repository gave us more pieces of our tree.

In our example, we operated only on the root of our working copy, changing its ambient depth value. But we can independently change the ambient depth value of any subdirectory inside the working copy, too. Careful use of this ability allows us to flesh out only certain portions of the working copy tree, leaving other portions absent altogether (hence the “sparse” bit of the feature's name). Here's an example of how we might build out a portion of one branch of our family's tree, enable full recursion on another branch, and keep still other pieces pruned (absent from disk).

$ rm -rf mom-empty
$ svn checkout file:///var/svn/repos mom-empty --depth empty
Checked out revision 1.
$ svn update --set-depth empty mom-empty/son
A    mom-empty/son
Updated to revision 1.
$ svn update --set-depth empty mom-empty/daughter
A    mom-empty/daughter
Updated to revision 1.
$ svn update --set-depth infinity mom-empty/daughter/granddaughter1
A    mom-empty/daughter/granddaughter1
A    mom-empty/daughter/granddaughter1/bunny1.txt
A    mom-empty/daughter/granddaughter1/bunny2.txt
Updated to revision 1.
$

Au fur et à mesure que nous avons augmenté le niveau de récursion, le dépôt a complété progressivement notre arborescence.

Dans notre exemple, nous n'avons agi que sur la racine de notre copie de travail, en changeant la valeur du niveau de récursion associé. Mais nous pouvons aussi changer de façon indépendante le niveau de récursion associé à chaque sous-répertoire de la copie de travail. Une utilisation minutieuse de cette option nous permet de récupérer uniquement certaines portions de la copie de travail, en laissant de côté toutes les autres portions (d'où le nom "clairsemé" de la fonctionnalité). Voici un exemple montrant comment construire une portion d'une branche de notre arbre généalogique, activer la récursion totale sur une autre branche et élaguer le reste (qui ne sera donc pas sur notre disque dur).

$ rm -rf maman-vide
$ svn checkout file:///var/svn/depot maman-vide --depth empty
Révision 1 extraite.
$ svn update --set-depth empty maman-vide/fils
A    maman-vide/fils
Actualisé à la révision 1.
$ svn update --set-depth empty maman-vide/fille
A    maman-vide/fille
Actualisé à la révision 1.
$ svn update --set-depth infinity maman-vide/fille/petite-fille1
A    maman-vide/fille/petite-fille1
A    maman-vide/fille/petite-fille1/lapinou1.txt
A    maman-vide/fille/petite-fille1/lapinou2.txt
Actualisé à la révision 1.
$

Paragraphe 11

Fortunately, having a complex collection of ambient depths in a single working copy doesn't complicate the way you interact with that working copy. You can still make, revert, display, and commit local modifications in your working copy without providing any new options (including --depth and --set-depth) to the relevant subcommands. Even svn update works as it does elsewhere when no specific depth is provided—it updates the working copy targets that are present while honoring their sticky depths.

Heureusement, même avec différents niveaux de récursion définis au sein d'une même copie de travail, les actions sur la copie de travail ne s'en trouvent pas plus compliquées. Vous pouvez toujours effectuer des modifications et les propager, revenir en arrière, ou afficher les modifications locales de votre copie de travail sans spécifier d'option particulière (y compris --depth and --set-depth) aux dites commandes. Même svn update fonctionne normalement quand on ne lui fournit pas de niveau de récursion spécifique : elle met à jour les cibles de la copie de travail qui sont présentes en tenant compte des niveaux de récursion qui leur sont associés.

Paragraphe 12

You might at this point be wondering, “So what? When would I use this?” One scenario where this feature finds utility is tied to a particular repository layout, specifically where you have many related or codependent projects or software modules living as siblings in a single repository location (trunk/project1, trunk/project2, trunk/project3, etc.). In such scenarios, it might be the case that you personally care about only a handful of those projects—maybe some primary project and a few other modules on which it depends. You can check out individual working copies of all of these things, but those working copies are disjoint and, as a result, it can be cumbersome to perform operations across several or all of them at the same time. The alternative is to use the sparse directories feature, building out a single working copy that contains only the modules you care about. You'd start with an empty-depth checkout of the common parent directory of the projects, and then update with infinite depth only the items you wish to have, like we demonstrated in the previous example. Think of it like an opt-in system for working copy citizens.

Vous devez vous demander : "Bien. Mais quand aurais-je besoin d'utiliser ça ?". Un cas classique est lié à une architecture du dépôt particulière : lorsque de nombreux projets et modules logiciels liés cohabitent au même niveau dans un dépôt (trunk/projet1, trunk/projet2, trunk/projet3, etc...). Dans de tels scénarios, il est probable que seuls quelques projets vous intéressent personnellement, sans doute pas plus d'un projet principal et de quelques autres modules dont il dépend. Vous pouvez extraire une copie de travail pour chacune de ces arborescences, mais ces copies de travail sont séparées et, par conséquence, il peut être fastidieux d'effectuer des opérations sur plusieurs ou sur l'ensemble des copies de travail en même temps. L'autre solution est d'utiliser la fonctionnalité de répertoires clairsemés, en construisant une seule copie de travail qui ne contient que les modules qui vous intéressent. Vous partez d'une extraction du répertoire parent commun aux différents projets avec un niveau zéro de récursion (empty-depth), puis vous mettez à jour avec un niveau infini de récursion les éléments que vous voulez récupérer, comme nous l'avons fait dans l'exemple précédent. Voyez ça comme un système d'inclusion optionnelle des éléments qui peuplent la copie de travail.

Paragraphe 13

Subversion 1.5's implementation of shallow checkouts is good but does not support a couple of interesting behaviors. First, you cannot de-telescope a working copy item. Running svn update --set-depth empty in an infinite-depth working copy will not have the effect of discarding everything but the topmost directory—it will simply error out. Second, there is no depth value to indicate that you wish an item to be explicitly excluded. You have to do implicit exclusion of an item by including everything else.

L'implémentation des extractions superficielles de Subversion 1.5 est relativement bonne, mais il y a deux choses intéressantes qu'elle ne permet pas de faire. Premièrement, vous ne pouvez pas diminuer le niveau de récursion d'un élément de la copie de travail. Si vous lancez svn update --set-depth empty sur une copie de travail de niveau de récursion infini, vous n'aurez pas l'effet attendu, qui serait de supprimer tout sauf le répertoire racine - cela renverra simplement une erreur. Deuxièmement, il n'y a pas de valeur de récursion pour indiquer que vous voulez exclure explicitement un élément. Vous devez effectuer une exclusion implicite de l'élément en incluant tous les éléments sauf celui-là.