Skip to content

Latest commit

 

History

History
75 lines (50 loc) · 2.61 KB

concepts.adoc

File metadata and controls

75 lines (50 loc) · 2.61 KB
Raw

Concepts

Symly is based on the following major concepts:

  • The *repositories*: Repositories are folders containing a file structured to be linked in a directory. For example /some/path, ~/repositories/defaults. You can specify one or more repositories. Each repository acts as a layer, overriding previous layers with its content.

  • The *directory*: The folder in which the repositories' content will be linked. For example ~.

Consider the following repository file structure:

~/repository
  |-- .gitconfig
  >-- .config
      >-- starship.toml

When linked with symly in the ~ directory, the following links will be created:

~/.gitconfig             -> ~/repository/.gitconfig
~/.config/starship.toml  -> ~/repository/config/starship.toml

Links are composed of two attributes:

  • source: The path of the link.

  • target: The path pointed by the link.

They are materialized on the file system as [symbolic links](https://en.wikipedia.org/wiki/Symbolic_link).

For example: ~/.config/starship.toml → ~/repository/.config/starship.toml

Those two attributes can be determined from the directory, and the repository using a third one: the link name.

The link name is the common part of the path between the link source and target. It is both:

  • The relative path of a link source to its main directory.

  • The relative path of a link target to its repository.

Example:

  • .gitconfig for link ~/.gitconfig → ~/repository/.gitconfig

  • .config/starship.toml for link ~/.config/starship.toml → ~/repository/.config/starship.toml

Summary

Here is how all the previous notions play together:

 ~          /  .config/starship.toml  ->  ~/repositories/defaults  /  .config/starship.toml
[DIRECTORY] / [NAME                 ] -> [REPOSITORY             ] / [NAME                 ]
[SOURCE                             ] -> [TARGET                                           ]

The "repository file tree is the state" principle

On top of those concepts, an important principle applies:

*The repository file tree is the state*

This principle has the following implications:

  • No command to add a file to a repository, just drop it there

  • No command to delete a file from a repository, just delete it

  • No command to edit a file in a repository, just edit it directly or through its symbolic link in the directory. This allows for seamless integration with tools modifying files directly. Like git config user.name …​ for example.

  • Immediate visibility of modifications made to the directory files

Let’s apply those concepts by looking at the usage manual.