.
675 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # `gitlinks` - Git Powered Go-Links
2 |
3 | Hosted "Go-Links" via Git and GitHub Pages
4 |
5 | pip install gitlinks
6 |
7 |
8 | 
9 |
10 |
11 | Jump to setup | By @logan_engstrom
12 |
13 |
14 |
15 | # Quick Overview
16 |
17 | gitlinks is a command line tool that maps custom shortlinks to URLs via
18 | Git and GitHub Pages .
19 | The following table shows example mappings for user lengstrom's gitlinks repository
20 | goto:
21 |
22 |
23 | | Key | URL | GitHub Pages Shortlink |
24 | | :------------ | :------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------- |
25 | | `zoom` | https://mit.zoom.us/j/95091088705 | http://loganengstrom.com/goto/zoom |
26 | | `classes/NLP` | https://canvas.mit.edu/courses/7503 | http://loganengstrom.com/goto/classes/nlp |
27 |
28 |
29 | Here, anyone can access the
30 | zoom link (https://mit.zoom.us/j/95091088705) at
31 | http://loganengstrom.com/goto/zoom
32 | (since the GitHub pages site lengstrom.github.io maps to loganengstrom.com).
33 | We can also organize keys through nesting, such as with classes/NLP.
34 |
35 |
36 | gitlinks works by storing state on GitHub
37 | and rendering structured redirects on GitHub pages. Add, remove, and visualize link mappings through the command line!
38 |
39 |
40 | ```
41 | $ gitlinks set zoom https://mit.zoom.us/j/95091088705
42 | => Success: Set key "zoom" → "https://mit.zoom.us/j/95091088705".
43 | ```
44 | ```
45 | $ gitlinks delete zoom
46 | => Success: Deleted key "zoom".
47 | ```
48 | ```
49 | $ gitlinks show
50 | => Checking for changes from remote...
51 | == GitLinks (Remote: git@github.com:lengstrom/goto.git) ==
52 | calendly → https://calendly.com/loganengstrom
53 | classes/18.102 → http://math.mit.edu/~rbm/18-102-S17/
54 | classes/6.005 → http://web.mit.edu/6.031/www/fa18/general/
55 | ffcv_slack → https://ffcv-workspace.slack.com/join/shared_invite/zt-11olgvyfl-dfFerPxlm6WtmlgdMuw_2A#/shared-invite/email
56 | papers/bugsnotfeatures → https://arxiv.org/abs/1905.02175
57 | zombocom → https://www.zombo.com
58 | zoom → https://mit.zoom.us/j/95091088705
59 | ```
60 |
61 |
62 | gitlinks also generates an index page: see
63 | http://loganengstrom.com/goto/ as an example. The big caveat of `gitlinks` is that all of your links are public to anyone on the web, so be careful with what you link!
64 |
65 |
66 | # Setup
67 | Configure `gitlinks` in two steps!
68 | ## First: Cook up a new GitHub Repository
69 |
70 | First, visit https://github.com/new and choose a short, memorable name like
71 | go for your gitlinks repository.
72 |
73 | 
74 |
75 | Now, check the box "Add a README file" (the repository can't be empty).
76 |
77 | 
78 |
79 | Make the repository, then go your repository's GitHub pages settings:
80 | https://github.com/yourusername/repository_name/settings/pages) and enable GitHub pages for the main branch:
81 |
82 | 
83 |
84 | ## Initialize `gitlinks` locally
85 |
86 | Install the gitlinks executable via pip: pip install gitlinks. Then,
87 | initialize gitlinks to use your repository: gitlinks init remote_url.
88 | Your remote_url can be found here:
89 |
90 | 
91 |
92 | After this step, you should be able to make go-links to your heart's content.
93 |
94 |
95 | # License
96 | GPL v3
97 |
--------------------------------------------------------------------------------
/gitlinks/__init__.py:
--------------------------------------------------------------------------------
1 | from .cli import main
--------------------------------------------------------------------------------
/gitlinks/cli.py:
--------------------------------------------------------------------------------
1 | """GitLinks: Command line client for managing GitHub pages-powered shortlinks.
2 | See https://github.com/lengstrom/gitlinks#setup for setup and additional usage
3 | information.
4 |
5 | Usage:
6 | gitlinks init
7 | gitlinks set
8 | gitlinks delete ...
9 | gitlinks show
10 | gitlinks cname
11 |
12 | Options:
13 | -h --help Show this screen.
14 | """
15 | from docopt import docopt
16 | from pathlib import Path
17 | import shutil
18 | import tabulate
19 | import json
20 | import git
21 | import pandas as pd
22 | import sys
23 | from ilock import ILock
24 |
25 | from .utils import (
26 | clone, query_yes_no, try_setup, serialize_csv, load_csv, commit_push,
27 | check_repo, generate_pages, plural_msg, clean, patch_url, reset_origin,
28 | ARROW, bolded, pprint, try_state
29 | )
30 |
31 | GIT_PATH = Path('~/.gitlinks/').expanduser()
32 | INDEX_NAME = 'index.csv'
33 | META_NAME = 'state.json'
34 |
35 | def get_state():
36 | return try_state(GIT_PATH, META_NAME)
37 |
38 | def set_state(k, v):
39 | state = get_state()
40 | state[k] = v
41 | json.dump(state, open(GIT_PATH / META_NAME, 'w+'))
42 | return state
43 |
44 | def initialize(url, path=GIT_PATH):
45 | if path.exists():
46 | msg = f'{path} already exists; really delete?'
47 | if query_yes_no(msg, default='yes'):
48 | shutil.rmtree(path)
49 | else:
50 | pprint('Ok, exiting.')
51 | return
52 |
53 | repo = clone(url, path)
54 | try_setup(repo, path, INDEX_NAME, META_NAME)
55 | pprint(f'Initialized gitlinks via {url}!')
56 |
57 | def set_link(key, url, df):
58 | url = patch_url(url)
59 | df = df[df.key != key]
60 | df = pd.concat([df, pd.DataFrame({
61 | 'key':[key],
62 | 'url':[url]
63 | })], ignore_index=True, axis=0)
64 |
65 | return df
66 |
67 | def delete_links(keys, df):
68 | keys = set(keys)
69 | return df[~df.key.isin(keys)]
70 |
71 | def show(df, repo):
72 | df[ARROW] = [ARROW for _ in range(df.shape[0])]
73 | new_order = [0, 2, 1]
74 | df = df[df.columns[new_order]]
75 | df = df.sort_values('key')
76 |
77 | rurl = repo.remotes.origin.url
78 | title = bolded(f'== GitLinks (Remote: {rurl}) ==')
79 | print(title)
80 | if df.shape[0] > 0:
81 | tab = tabulate.tabulate(df, df.columns, colalign=('left', 'center', 'left'),
82 | showindex=False)
83 | # width = tab.split('\n')[0].index(ARROW) - len(title)//2
84 | # width = min(0, width)
85 | # print(' ' * width + title)
86 | rows = '\n'.join(tab.split('\n')[2:])
87 | print(rows)
88 | else:
89 | pprint('Empty, no keys to display!')
90 |
91 | state = get_state()
92 | if len(state.keys()) > 0:
93 | pprint('State:')
94 | for k, v in state.items():
95 | pprint(f'=> {k} = {v}')
96 |
97 | def execute(args, git_path=GIT_PATH):
98 | if args['init']:
99 | return initialize(args[''], path=git_path)
100 |
101 | try:
102 | repo = git.Repo(git_path)
103 | assert check_repo(repo, INDEX_NAME)
104 | except:
105 | msg = "No initialized repo; run `gitlinks init ` first!"
106 | raise ValueError(msg)
107 |
108 | csv_path = git_path / INDEX_NAME
109 | df = load_csv(csv_path)
110 |
111 | reset_origin(repo)
112 | clean(repo)
113 | pprint(f'Checking for changes from remote...')
114 | repo.remotes.origin.pull()
115 |
116 | if args['show']:
117 | return show(df, repo)
118 |
119 | if args['set']:
120 | key = args[''][0]
121 | assert key[-1] != '/', f'Key "{key}" should not end with a "/"!'
122 | url = args['']
123 | df = set_link(key, url, df)
124 | print_msg = f'Set key "{bolded(key)}" {bolded(ARROW)} "{bolded(url)}"'
125 | commit_msg = f'Set key "{key}" {ARROW} "{url}"'
126 | elif args['delete']:
127 | keys = args['']
128 | poss = set(df.key)
129 | deletable = [k for k in keys if k in poss]
130 | df = delete_links(deletable, df)
131 |
132 | not_deletable = set(keys) - set(deletable)
133 | if not_deletable:
134 | msg = 'Key{plural} {keys_pretty} not present...'
135 | pprint(plural_msg(not_deletable, msg))
136 |
137 | msg = 'Deleted key{plural} {keys_pretty}'
138 | print_msg = plural_msg(deletable, msg, bold=True)
139 | commit_msg = plural_msg(deletable, msg, bold=False)
140 |
141 | if len(deletable) == 0:
142 | pprint('No keys to remove, exiting!')
143 | return
144 |
145 | if args['cname']:
146 | cname = args['']
147 | set_state('CNAME', cname)
148 | print_msg = f'Set CNAME to {cname}.'
149 | commit_msg = print_msg
150 | else:
151 | cname = None
152 |
153 | serialize_csv(df, csv_path)
154 | generate_pages(df, git_path, INDEX_NAME, get_state())
155 |
156 | try:
157 | pprint('Committing and pushing...')
158 | commit_push(repo, commit_msg[:50])
159 | pprint(f'{bolded("Success")}: {print_msg}.')
160 | except Exception as e:
161 | reset_origin(repo)
162 | pprint(f'Failed; rolling back.')
163 | raise e
164 |
165 | def main():
166 | if len(sys.argv) == 1:
167 | sys.argv.append('-h')
168 |
169 | args = docopt(__doc__)
170 | with ILock('gitlinks'):
171 | execute(args)
172 |
173 | if __name__ == '__main__':
174 | main()
175 |
--------------------------------------------------------------------------------
/gitlinks/utils.py:
--------------------------------------------------------------------------------
1 | import git
2 | from collections import defaultdict
3 | from git import RemoteProgress
4 | import pandas as pd
5 | import shutil
6 | import sys
7 | from pathlib import Path
8 | import requests
9 | import json
10 |
11 | ARROW = '→'
12 | DEFAULT_PROTECTED = ['.git', 'CNAME']
13 | GA = """
14 |
15 |
24 |
25 | """
26 |
27 | def try_state(git_path, meta_name):
28 | p = Path(git_path / meta_name)
29 | return json.load(open(p, 'r'))
30 |
31 | def pprint(x):
32 | msg = bolded('=> ') + x
33 | print(msg)
34 |
35 | def bolded(x):
36 | return "\033[1m" + x + "\033[0m"
37 |
38 | def empty_csv():
39 | return pd.DataFrame({
40 | 'key':[],
41 | 'url':[]
42 | })
43 |
44 | def serialize_csv(df, path):
45 | df.to_csv(str(path), index=False)
46 |
47 | def load_csv(f):
48 | return pd.read_csv(str(f))
49 |
50 | class CloneProgress(RemoteProgress):
51 | def update(self, op_code, cur_count, max_count=None, message=''):
52 | if message:
53 | print(message)
54 |
55 | def clone(url, path):
56 | prog = CloneProgress()
57 | return git.Repo.clone_from(url, path, progress=prog)
58 |
59 | def commit_push(repo, commit_msg):
60 | repo.git.add(all=True)
61 | repo.index.commit(commit_msg)
62 | origin = repo.remote(name='origin')
63 | origin.push()
64 |
65 | def clean(repo):
66 | repo.git.clean('-xdf')
67 |
68 | def check_repo(repo, index_name):
69 | wd = repo.working_dir
70 | try:
71 | load_csv(str(Path(wd) / index_name))
72 | return True
73 | except:
74 | return False
75 |
76 | def wipe_directory(dired, protected):
77 | protected = set(protected + DEFAULT_PROTECTED)
78 | for child in dired.iterdir():
79 | not_protected = child.name not in protected
80 | is_dir = child.is_dir()
81 | is_index = child.name == 'index.html'
82 | if not_protected and (is_dir or is_index):
83 | if child.is_dir():
84 | shutil.rmtree(child)
85 | else:
86 | child.unlink()
87 |
88 | def try_setup(repo, path, index_name, state_name):
89 | # path is the path of a git repository
90 | # Clean up any non-tracked changes
91 | # Then check if there's an index.csv; if so, exit
92 | # If no index.csv, delete everything in repo, make an empty index.csv
93 | clean(repo)
94 | index_path = path / index_name
95 | state_path = path / state_name
96 |
97 | if not check_repo(repo, index_name):
98 | pprint('Not a valid repo; reinitializing.')
99 | # delete everything in directory
100 | wipe_directory(path, ['.git'])
101 |
102 | empty = empty_csv()
103 | serialize_csv(empty, index_path)
104 | json.dump({}, open(state_path, 'w+'))
105 |
106 | try:
107 | commit_push(repo, 'Initialization')
108 | except Exception as e:
109 | pprint('Remote update failed; try initializing again!')
110 | raise e
111 |
112 | def template_maker(url):
113 | return f''
114 |
115 | def prettify_list(ls, bold=True):
116 | if bold:
117 | func = lambda x:f'"{bolded(x)}"'
118 | else:
119 | func = lambda x:f'"{x}"'
120 |
121 | return ", ".join(map(func, ls))
122 |
123 | def generate_pages(df, working_dir, index_name, state):
124 | wd = Path(working_dir)
125 | if 'CNAME' in state:
126 | cname = state['CNAME']
127 | with open(wd / cname, 'w+') as f:
128 | f.write(cname)
129 | if 'GA Property ID' in state:
130 | prop_id = state['GA Property ID']
131 | else:
132 | prop_id = None
133 |
134 | protected = ['.git', index_name]
135 | wipe_directory(wd, protected)
136 |
137 | pprint('Rebuilding HTML...')
138 | iterator = df.sort_values('key').iterrows()
139 | inner_list = []
140 | for _, row in iterator:
141 | key, url = row.key, row.url
142 | html_file = wd / (key + '/index.html')
143 | parent = html_file.parent
144 | parent.mkdir(exist_ok=True, parents=True)
145 |
146 | with open(html_file, 'w+') as f:
147 | f.write(template_maker(url))
148 |
149 | inner_list.append(f'| {key} | {ARROW} | {url} | ')
150 |
151 | with open(wd / 'index.html', 'w+') as index_file:
152 | html = (f'''
153 | gitlinks
154 |
163 | gitlinks
164 | ''')
165 | if prop_id:
166 | html = html + GA.format(prop_id)
167 |
168 | index_file.write(html)
169 |
170 | def url_exists(url):
171 | try:
172 | request = requests.get(url, timeout=0.5)
173 | return True
174 | except:
175 | return False
176 |
177 | def plural_msg(ls, fmt_str, bold=True):
178 | plural = 's' if len(ls) > 1 else ''
179 | keys_pretty = prettify_list(ls, bold=bold)
180 | return fmt_str.format(plural=plural, keys_pretty=keys_pretty)
181 |
182 | def reset_origin(repo):
183 | repo.git.reset('--hard', f'origin/{repo.active_branch}')
184 |
185 | def patch_url(url):
186 | if url[:4] == 'http':
187 | return url
188 | else:
189 | if url_exists('https://' + url):
190 | protocol = 'https://'
191 | elif url_exists('http://' + url):
192 | protocol = 'http://'
193 | else:
194 | protocol = None
195 |
196 | if protocol:
197 | patched = f'{protocol}{url}'
198 | pprint(f'No schema given for "{url}"! Patching to "{patched}"...')
199 | return patched
200 | else:
201 | pprint(f'No schema given for URL "{url}"!')
202 | msg = f'No valid schema for given URL! Did you mean "http://{url}"?'
203 | raise ValueError(msg)
204 |
205 | # This is from StackOverflow.
206 | def query_yes_no(question, default="yes"):
207 | """Ask a yes/no question via raw_input() and return their answer.
208 |
209 | "question" is a string that is presented to the user.
210 | "default" is the presumed answer if the user just hits .
211 | It must be "yes" (the default), "no" or None (meaning
212 | an answer is required of the user).
213 |
214 | The "answer" return value is True for "yes" or False for "no".
215 | """
216 | valid = {"yes": True, "y": True, "ye": True,
217 | "no": False, "n": False}
218 | if default is None:
219 | prompt = " [y/n] "
220 | elif default == "yes":
221 | prompt = " [Y/n] "
222 | elif default == "no":
223 | prompt = " [y/N] "
224 | else:
225 | raise ValueError("invalid default answer: '%s'" % default)
226 |
227 | while True:
228 | sys.stdout.write(question + prompt)
229 | choice = input().lower()
230 | if default is not None and choice == '':
231 | return valid[default]
232 | elif choice in valid:
233 | return valid[choice]
234 | else:
235 | sys.stdout.write("Please respond with 'yes' or 'no' "
236 | "(or 'y' or 'n').\n")
237 |
--------------------------------------------------------------------------------
/pyproject.toml:
--------------------------------------------------------------------------------
1 | [build-system]
2 | requires = [
3 | "setuptools>=42",
4 | "wheel"
5 | ]
6 | build-backend = "setuptools.build_meta"
--------------------------------------------------------------------------------
/setup.py:
--------------------------------------------------------------------------------
1 | #!/usr/bin/env python
2 | # -*- coding: utf-8 -*-
3 | # stolen from imgcat: https://github.com/wookayin/python-imgcat/blob/master/setup.py
4 |
5 | import sys
6 | import os
7 | import re
8 | from setuptools import setup, Command
9 |
10 | with open("README.md", "r") as fh:
11 | long_description = fh.read()
12 |
13 | # setuptools.setup(
14 | # name='gitlinks',
15 | # version='0.2',
16 | # author='Logan Engstrom',
17 | # author_email='logan@mit.edu',
18 | # description='GitHub pages-powered shortlinks.',
19 | # long_description=long_description,
20 | # long_description_content_type="text/markdown",
21 | # url='https://github.com/lengstrom/gitlinks',
22 | # packages=setuptools.find_packages(),
23 | # install_requires=[
24 | # ],
25 | # entry_points={
26 | # 'console_scripts':['gitlinks=gitlinks.cli:main']
27 | # },
28 | # classifiers=[
29 | # "Programming Language :: Python :: 3",
30 | # "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
31 | # "Operating System :: OS Independent",
32 | # "Development Status :: 4 - Beta",
33 | # "Environment :: Console"
34 | # ],
35 | # )
36 |
37 | __PATH__ = os.path.abspath(os.path.dirname(__file__))
38 |
39 | def read_readme():
40 | with open('README.md') as f:
41 | return f.read()
42 |
43 |
44 | install_requires = [
45 | 'docopt>=0.6.2',
46 | 'GitPython>=3.1.13',
47 | 'ilock>=1.0.3',
48 | 'pandas>=1.2.2',
49 | 'portalocker>=2.2.1',
50 | 'requests>=2.25.1',
51 | 'requests-toolbelt>=0.9.1',
52 | 'tabulate>=0.8.9',
53 | 'tqdm>=4.58.0',
54 | 'twine'
55 | ]
56 |
57 | tests_requires = [
58 | 'pytest<5.0'
59 | ]
60 |
61 | __version__ = str(0.3)
62 |
63 |
64 | # brought from https://github.com/kennethreitz/setup.py
65 | class DeployCommand(Command):
66 | description = 'Build and deploy the package to PyPI.'
67 | user_options = []
68 |
69 | def initialize_options(self): pass
70 | def finalize_options(self): pass
71 |
72 | @staticmethod
73 | def status(s):
74 | print(s)
75 |
76 | def run(self):
77 | import twine # we require twine locally
78 |
79 | assert 'dev' not in __version__, \
80 | "Only non-devel versions are allowed. __version__ == {}".format(__version__)
81 |
82 | with os.popen("git status --short") as fp:
83 | git_status = fp.read().strip()
84 | if git_status:
85 | print("Error: git repository is not clean.\n")
86 | os.system("git status --short")
87 | sys.exit(1)
88 |
89 | try:
90 | from shutil import rmtree
91 | self.status('Removing previous builds ...')
92 | rmtree(os.path.join(__PATH__, 'dist'))
93 | except OSError:
94 | pass
95 |
96 | self.status('Building Source and Wheel (universal) distribution ...')
97 | os.system('{0} setup.py sdist'.format(sys.executable))
98 |
99 | self.status('Uploading the package to PyPI via Twine ...')
100 | os.system('twine upload dist/*')
101 |
102 | self.status('Creating git tags ...')
103 | os.system('git tag v{0}'.format(__version__))
104 | os.system('git tag --list')
105 | sys.exit()
106 |
107 | setup(
108 | name='gitlinks',
109 | version=__version__,
110 | license='MIT',
111 | description='GitHub pages-powered golinks',
112 | long_description=long_description,
113 | long_description_content_type="text/markdown",
114 | url='https://github.com/lengstrom/gitlinks',
115 | author='Logan Engstrom',
116 | author_email='engstrom@mit.com',
117 | keywords='golinks github pages',
118 | classifiers=[
119 | # https://pypi.python.org/pypi?%3Aaction=list_classifiers
120 | 'Development Status :: 3 - Alpha',
121 | 'License :: OSI Approved :: MIT License',
122 | 'Operating System :: POSIX :: Linux',
123 | 'Programming Language :: Python :: 2.7',
124 | 'Programming Language :: Python :: 3',
125 | ],
126 | packages=['gitlinks'],
127 | install_requires=install_requires,
128 | setup_requires=['pytest-runner<5.0'],
129 | tests_require=tests_requires,
130 | entry_points={
131 | 'console_scripts': ['gitlinks=gitlinks:main'],
132 | },
133 | include_package_data=True,
134 | zip_safe=False,
135 | cmdclass={
136 | 'deploy': DeployCommand,
137 | },
138 | python_requires=">=3.6")
--------------------------------------------------------------------------------
/static/add_readme.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/lengstrom/gitlinks/896b905a147ed9bc63af8db12c1415c16c14ee6b/static/add_readme.png
--------------------------------------------------------------------------------
/static/demo.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/lengstrom/gitlinks/896b905a147ed9bc63af8db12c1415c16c14ee6b/static/demo.gif
--------------------------------------------------------------------------------
/static/enable_ghpages.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/lengstrom/gitlinks/896b905a147ed9bc63af8db12c1415c16c14ee6b/static/enable_ghpages.png
--------------------------------------------------------------------------------
/static/make_repo.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/lengstrom/gitlinks/896b905a147ed9bc63af8db12c1415c16c14ee6b/static/make_repo.png
--------------------------------------------------------------------------------
/static/remote_url.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/lengstrom/gitlinks/896b905a147ed9bc63af8db12c1415c16c14ee6b/static/remote_url.png
--------------------------------------------------------------------------------
/static/usage.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/lengstrom/gitlinks/896b905a147ed9bc63af8db12c1415c16c14ee6b/static/usage.png
--------------------------------------------------------------------------------