Skip to content

Docs and customised paths #69

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
fredcooke wants to merge 6 commits into
base: master
Choose a base branch
from
Open

Docs and customised paths #69

Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
83ab6d9
Clarify the init instructions a bit.
fredcooke Apr 22, 2021
e62dd29
Add documentation for the optional setup parameters commonly found in…
fredcooke Apr 23, 2021
43b6a1f
Correct use of single and triple back ticks for quoting short strings…
fredcooke Apr 23, 2021
8699728
WIP: Flesh out a section on modifying default branchout behaviour, wh…
fredcooke Apr 23, 2021
8750fce
WIP eventual squash add some likely false assertions about the config…
fredcooke Apr 23, 2021
9f1dd8d
WIP Add draft glossary markdown document to be discussed/completed an…
fredcooke Apr 23, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 55 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,35 +40,82 @@ brew tap Branchout/homebrew-branchout
brew install branchout
```

### Initialise an existing organisation
### Initialise an existing or new organisation

To start with an existing project just init it from the git url

```
branchout init https://github.com/Branchout/branchout-reactor.git
branchout init https://github.com/Branchout/branchout-reactor.git [optionalDirName]
cd ~/project/branchout-reactor
branchout status
branchout pull
```

This will create the Branchoutfile and Branchoutprojects if needed
This will create the Branchoutfile and Branchoutprojects if needed, for example if the repo is new/empty and you're setting it up for the first time.

The default branchout name is the name of the root project
The default branchout name is the name of the root project, but can be overridden.

You can now add projects
```branchout add <project-name>```

They will show as not cloned until you ```branchout pull```
```
branchout add <project-name>
```

They will show as not cloned until you `branchout pull`

If you want to clone when you add
```branchout clone <project-name>```

```
branchout clone <project-name>
```

### Need to trust a certificate or ca bundle

If you have a corporate CA bundle that you need to trust just add it at `<metarepo>/.branchout/cacerts`

branchout-yarn will configure the environment so that yarn can trust certificates in or signed by certificates in cacarts

### Common config in Branchoutfile

#### Repo name prefixes

If in your git structure your repos are all commonly prefixed with the same thing, and you'd like that to be ignored by Branchout as a prefix, then add:

```
BRANCHOUT_PREFIX=prefix-without-trailing-hyphen
```

to the Branchoutfile and you'll get whatever the next hyphen-separated part is used as the group for directory layout.

#### Branchout name override

In case of your branchout repository having a long name that you don't want as part of the two branchout paths, you can override by adding:

```
BRANCHOUT_NAME=shorter-name
```

to the Branchoutfile and ideally use the same value as the optionalDirName during branchout init.

### Personal customisation

Sometimes the branchout defaults don't work for a particular scenario even though they do work for most of your colleagues.

@stickycode stickycode Apr 23, 2021

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

see this is the problem... they should work for everyone or no one... there aren't really special cases for people although the org might be special

@fredcooke fredcooke Apr 23, 2021

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Take a step back. What's important about this tool is NOT conformity and control of author over the world.

What's important about this tool is:

  • Documenting a set of repos for a particular purpose within an organisation or for the public
  • Efficiently managing large numbers of repos in a clean/easy way
  • Consistent tooling for building projects with separated/isolated software repos
  • Helper tooling for common things done on sets of projects (eg consistent git email and sshCommand config set on clone, may not be available yet, but I'm keen to add it)
  • Consistent structure within a set of repos (currently only one style supported, but a few others have been brewing in my head for a while, keen to implement and use)

And all of that stuff is GREAT and a good reason for me to burn my personal time on this in the coming months, happy to become contributor number two to your project/great idea! :-D

Where on your disk those two roots are is NOT important, not even when you share a path to a colleague, unless they're of below average intelligence. The only part of the path that is key to consistency/understanding should be the BRANCHOUT_NAME within those two root directories, wherever they are. Typically paths I give to colleagues are in the context of the repo that the discussion is about, eg src/main/java/ or whatever, not full absolute paths that may mean nothing on their disparate operating systems anyway.

On my machine ~/ is cleared out every night at 4am against a whitelist so I had to update that whitelist to add two more entries and every time I ls -al ~/ I see ~20% extra stuff that I don't want to. My personal structure after this is changed will be:

~/repos/branchoutRoots

and

~/repos/branchout/cacheAndSettingsRoots/

then it'll all be in one place, nice and handy right next to my not-yet-managed-by-branchout structures that I'd LOVE to port over :-D

I've told you before, I love this project. And I've also told you, it doesn't 100% work for me, yet. This is a step in the right direction that will also help many others with unpleasant usage situations to deal with get the best out of the tool in environments that they don't fully control.

@stickycode stickycode Jun 27, 2021

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sounds reasonable

One example is that the `${HOME}` places the two root directories on a very slow network drive.
Another might be that you already have a tree with your code and you want to keep it all together.
In cases like these you can use the following two files to ????

```
~/.config/Branchoutrc?

@stickycode stickycode Apr 23, 2021

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is correct

${BRANCHOUT_BASE}/.branchoutrc

@stickycode stickycode Apr 23, 2021

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

whats branchout base?

@stickycode stickycode Apr 23, 2021

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

are you thinking a common place like the metarepo? i guess that would work

BRANCHOUT_PROJECTION_DIRECTORY

@stickycode stickycode Apr 23, 2021

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i guess it could be absolute but that just is hard if you have multiple platforms

@fredcooke fredcooke Apr 23, 2021

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good question, both of these two lines were for you to confirm/rewrite in a way that makes sense. They were just guesses.

I'll add a glossary from the source code, maybe in a different file? And we can get on the same page terminology/jargon wise there.

```
#### Moving the branchout projects base dir

To set the root of where branchout initialises branchout repos do XXX

@stickycode stickycode Apr 23, 2021

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

set BRANCHOUT_PROJECTS_DIRECTORY in ~/.config/branchoutrc

@fredcooke fredcooke Apr 23, 2021

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@stickycode Is this true? Where I saw this used it was used on top of ${HOME} and it would be perfectly reasonable to put it on another drive mounted under for example /code or whatever that's outside ~/ - one such reason that I've hit in the past is limited path names in ubuntu with encrypted home functionality. I had to have my repos outside of ~/ for that reason.

Do we need a new variable that overrides both this and the base path being $HOME or just a wrapper layer around home that uses home as a default and lets you override it to eg / or wherever else you want it?


#### Moving the branchout caching base dir

To set the root of where branchout stores project specific caches and settings/credentials do YYY

@stickycode stickycode Apr 23, 2021

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i guess this should be similar BRANCHOUT_STATES_DIRECTORY in ~/.config/branchoutrc

@fredcooke fredcooke Apr 23, 2021

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See other comments above, if we keep this relative to the current $HOME and then just move the base of both that could be good enough, or might be better to have the two base values also be separate?


## Grokking the code and contributing


Expand All @@ -84,7 +131,7 @@ brew install git bats-core shellcheck

The tests are written in bats https://github.com/bats-core/bats-core

Note, the ```sstephenson/bats``` repository is unmaintained, bats-core is what you want.
Note, the `sstephenson/bats` repository is unmaintained, bats-core is what you want.

```
make test
Expand Down