docs: write more guides

[mattblovell]

Edit by @dmerejkowsky, so that the task list appears in the issue: Guides to write:

• [x] Creating a basic manifest repo, using init and sync
• [x] Editing .tsrc/manifest.yml
• [x] Using groups
• [x] Using several remotes
• [x] Editing the manifest safely (using apply-manifest before running git push)
• [x] Hacking tsrc behavior using tsrc foreach and env variables
• [x] Using fixed refs (tags and sha1)
• [x] Performing file system operations
• [ ] Using several manifest branches
• [ ] Selecting repos ( --all-cloned, --groups, --iregex)
• [ ] Using shallow clones
• [ ] Using tsrc for CI (reproducible builds, GitLab CI URLS ...)

Original issue below

Would it be possible (as time permits, naturally) to add additional examples or use cases to the online documentation. At present, there is a "Basic usage" section, which gets one up and going, and a full "Reference" section.

It would be nice to have a full (i.e., complete) example of using tsrc to

• populate a workspace consisting of multiple repos,
• tagging and/or branching (establishing a common tag/branch name across multiple repos),
• switching branches, and
• committing changes (although I don't know if tsrc is intended for that purpose or if commits and pushes are intended to just use git directly).

To provide a little more context...

At work, I've only recently switched into a group that is using git. Previously, I used git to maintain my own code even though the company was making use of a different tool. (So, it was set of fairly lonely repositories with only a single contributor!)

My new group typically has workspaces that each consists of files from 3 distinct repos, each cloned into distinct directories:

1. testbench code for an ASIC/FPGA design (forms the top-level directory)
2. the SystemVerilog code for the design (under that top-level directory, cleverly-named design)
3. library code for the testbench (in yet another directory beneath the top-level)

So, an example workspace would have a structure like project1-tb project1-tb/design project1-tb/library

(The top-level directory has contents other than design/ and library/, but those are all part of that testbench repository.)

Thus far, they've been content creating new workspaces via manually-invoked git clone commands, with dispersed group knowledge of what branches of, say, the library a given testbench needs. As the "new guy", I naturally stumbled over this, pulling the wrong branch of things and getting quite confused where I was supposed to find certain code.

There is also currently no general, automated mechanism by which scripts can pull / create a workspace (for, say, running regression tests on the design).

I think tsrc could be a useful tool for my team, even though it involves a little bit of change. (Normally, the testbench directory inherently forms the start of a new workspace. I think the manifest approach adds another directory, although I think I saw a feature request for cloning into "." and using relative paths for subdirectories?)

So, I'm trying to understand the intended use models for tsrc. Some more complete online examples would also serve as good starting points when I try to introduce tsrc to the team.

Thanks for making tsrc available, BTW!

[dmerejkowsky]

Thus far, they've been content creating new workspaces via manually-invoked git clone commands, with dispersed group knowledge of what branches of, say, the library a given testbench needs. As the "new guy", I naturally stumbled over this, pulling the wrong branch of things and getting quite confused where I was supposed to find certain code.

Good news: this is exactly the type of problems tsrc is trying to solve :)

I think I saw a feature request for cloning into "." and using relative paths for subdirectories?)

Yeah .. don't do that unless you have to. It was not a really good example.

It would be nice to have a full (i.e., complete) example of using tsrc to [...]

Good idea. I think a "use cases" section in the doc would be useful indeed. Thanks for the suggestion :)