diff options
author | Monty Taylor <mordred@inaugust.com> | 2017-06-20 11:18:28 -0500 |
---|---|---|
committer | Monty Taylor <mordred@inaugust.com> | 2017-06-20 11:18:28 -0500 |
commit | 58b136fb2559415ec10f8252c8bb3b02f997d257 (patch) | |
tree | 929a75dbf9d920f95dd9bb38b92bc2f67303f707 /README.rst |
Diffstat (limited to 'README.rst')
-rw-r--r-- | README.rst | 72 |
1 files changed, 72 insertions, 0 deletions
diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..12ba356 --- /dev/null +++ b/README.rst | |||
@@ -0,0 +1,72 @@ | |||
1 | src.sh | ||
2 | ====== | ||
3 | |||
4 | Simple shell function to clone and navigate git source respositories in a | ||
5 | golang-style directory layout. | ||
6 | |||
7 | golang dictates a strict directory layout and provides helper programs to | ||
8 | fetch source code into the right structure. Other languages do not mandate such | ||
9 | a layout, but neither do they have any problems if one is used. ``src.sh`` was | ||
10 | written to facilitate managing all of ones source repos in the same structure, | ||
11 | regardless of whether one is programming in go or not. | ||
12 | |||
13 | Installation | ||
14 | ------------ | ||
15 | |||
16 | Either copy the contents of ``src.sh`` to your ``~/.bash_profile`` or | ||
17 | copy the file into ``/etc/profile.d`` then re-login. It's also possible | ||
18 | to ``source src.sh`` in the current shell if you don't want to re-login. | ||
19 | |||
20 | A new shell function `src` will be available. | ||
21 | |||
22 | Usage | ||
23 | ----- | ||
24 | |||
25 | ``src.sh`` either clones or changes directories to a given source repo | ||
26 | location. | ||
27 | |||
28 | .. code-block:: bash | ||
29 | |||
30 | src emonty/src.sh | ||
31 | |||
32 | Results in the ``emonty/src.sh`` repo being cloned to | ||
33 | ``~/src/github.com/emonty/src.sh`` if it's not already there and that being set | ||
34 | to the current directory. | ||
35 | |||
36 | Configuration | ||
37 | ------------- | ||
38 | |||
39 | ``src.sh`` uses the golang source directory layout scheme, but uses | ||
40 | ``$SRCSRCDIR`` instead of ``$GOPATH`` as the primary variable. If ``$GOPATH`` | ||
41 | is set and ``$SRCSRCDIR`` is not set, ``$SRCSRCDIR`` defaults to | ||
42 | ``$GOPATH/src``. If neither are set, ``$SRCSRCDIR`` defaults to ``~/src``. | ||
43 | |||
44 | ``$SRCSRCDIR``, while ugly, was chosen because the function is called "src" but | ||
45 | ``$SRCDIR`` is much more likely to be already be used, possibly for some other | ||
46 | purpose. | ||
47 | |||
48 | ``src.sh`` supports a configurable ordered list of prefixes to try, for folks | ||
49 | who have frequent groups of things they work with. ``$SRCSRCPREFIXES`` | ||
50 | defaults to "github.com". For instance: | ||
51 | |||
52 | .. code-block:: bash | ||
53 | |||
54 | export SRCSRCPREFIXES="git.openstack.org/openstack-infra \ | ||
55 | git.openstack.org/openstack \ | ||
56 | github.com" | ||
57 | src shade | ||
58 | |||
59 | Results in shade being cloned to | ||
60 | ``~/src/git.openstack.org/openstack-infra/shade``. | ||
61 | |||
62 | ``src.sh`` defaults to using cd to change directories. Setting | ||
63 | ``$SRCSRCUSEPUSHD=1`` will cause it to use pushd instead. | ||
64 | |||
65 | Use of go get by default | ||
66 | ------------------------ | ||
67 | |||
68 | By default, ``src.sh`` uses ``go get -d`` to do the cloning. If you do not have | ||
69 | ``go get`` in your path, it will use a less efficient set of shell commands | ||
70 | and attempt cloning directly. ``go get`` has a better idea of whether or not | ||
71 | you're requesting a full path to something or not, so it's recommended to just | ||
72 | have it installed somewhere in your path. | ||